1.1 --- a/it/00book.xml	Fri Jul 24 19:23:29 2009 +0200
     1.2 +++ b/it/00book.xml	Sat Jul 25 16:48:03 2009 +0200
     1.3 @@ -17,8 +17,8 @@
     1.4  <!ENTITY ch08     SYSTEM "ch08-branch.xml">
     1.5  <!ENTITY ch09     SYSTEM "ch09-undo.xml">
     1.6  <!ENTITY ch10     SYSTEM "ch10-hook.xml">
     1.7 +<!ENTITY ch11     SYSTEM "ch11-template.xml">
     1.8  <!--
     1.9 -<!ENTITY ch11     SYSTEM "ch11-template.xml">
    1.10  <!ENTITY ch12     SYSTEM "ch12-mq.xml">
    1.11  <!ENTITY ch13     SYSTEM "ch13-mq-collab.xml">
    1.12  <!ENTITY ch14     SYSTEM "ch14-hgext.xml">
    1.13 @@ -107,8 +107,8 @@
    1.14    &ch09;
    1.15    <!-- BEGIN ch10 -->
    1.16    &ch10;
    1.17 -  <!-- BEGIN ch11
    1.18 -  &ch11; -->
    1.19 +  <!-- BEGIN ch11 -->
    1.20 +  &ch11;
    1.21    <!-- BEGIN ch12
    1.22    &ch12; -->
    1.23    <!-- BEGIN ch13

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/it/ch11-template.xml	Sat Jul 25 16:48:03 2009 +0200
     2.3 @@ -0,0 +1,344 @@
     2.4 +<chapter id="chap:template">
     2.5 +  <?dbhtml filename="personalizzare-l-output-di-mercurial.html"?>
     2.6 +  <title>Personalizzare l'output di Mercurial</title>
     2.7 +
     2.8 +  <para id="x_578">Mercurial offre un potente meccanismo basato sui template per permettervi di controllare il modo in cui visualizza le informazioni. Potete usare i template per generare uno specifico output per un singolo comando, o per personalizzare l'intera apparenza dell'interfaccia web predefinita.</para>
     2.9 +
    2.10 +  <sect1 id="sec:style">
    2.11 +    <title>Usare gli stili di output già pronti</title>
    2.12 +
    2.13 +    <para id="x_579">Distribuiti con Mercurial ci sono alcuni stili di output che potete usare immediatamente. Uno stile è semplicemente un template già pronto che qualcuno ha scritto e installato da qualche parte che Mercurial può trovare.</para>
    2.14 +
    2.15 +    <para id="x_57a">Prima di dare un'occhiata agli stili inclusi in Mercurial, rivediamo il suo output normale.</para>
    2.16 +
    2.17 +    &interaction.template.simple.normal;
    2.18 +
    2.19 +    <para id="x_57b">Questo ci dà qualche informazione, ma porta via un sacco di spazio&emdash;cinque righe di output per ogni changeset. Lo stile <literal>compact</literal> riduce questo spazio a tre righe, presentate in maniera sparsa.</para>
    2.20 +
    2.21 +    &interaction.template.simple.compact;
    2.22 +
    2.23 +    <para id="x_57c">Lo stile <literal>changelog</literal> ci suggerisce quale sia il potere espressivo del motore di template di Mercurial. Questo stile tenta di seguire le linee guida per i registri dei cambiamenti stabilite dal progetto GNU<citation>web:changelog</citation>.</para>
    2.24 +
    2.25 +    &interaction.template.simple.changelog;
    2.26 +
    2.27 +    <para id="x_57d">Non vi impressionerà sapere che lo stile di output predefinito di Mercurial è chiamato <literal>default</literal>.</para>
    2.28 +
    2.29 +    <sect2>
    2.30 +      <title>Impostare uno stile predefinito</title>
    2.31 +
    2.32 +      <para id="x_57e">Potete modificare lo stile di output che Mercurial userà per ogni comando modificando il vostro file <filename role="special">~/.hgrc</filename>, nominando lo stile che preferireste usare.</para>
    2.33 +
    2.34 +      <programlisting>[ui]
    2.35 +style = compact</programlisting>
    2.36 +
    2.37 +      <para id="x_57f">Se scrivete un vostro stile, potete usarlo inserendo il percorso del vostro file di stile, oppure copiano il vostro file di stile in un luogo dove Mercurial possa trovarlo (tipicamente la sottodirectory <literal>templates</literal> della vostra directory di installazione di Mercurial).</para>
    2.38 +    </sect2>
    2.39 +  </sect1>
    2.40 +
    2.41 +  <sect1>
    2.42 +    <title>Comandi che supportano stili e template</title>
    2.43 +
    2.44 +    <para id="x_580">Tutti i comandi Mercurial di tipo <literal>log</literal> vi permettono di usare stili e template: <command role="hg-cmd">hg incoming</command>, <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg outgoing</command>, and <command role="hg-cmd">hg tip</command>.</para>
    2.45 +
    2.46 +    <para id="x_581">Al momento in cui scrivo questo manuale, questi sono i comandi che finora supportano stili e template. Dato che questi sono i comandi più importanti che hanno bisogno di un output personalizzabile, c'è stata poca pressione da parte della comunità utenti di Mercurial per aggiungere il supporto per stili e template ad altri comandi.</para>
    2.47 +  </sect1>
    2.48 +
    2.49 +  <sect1>
    2.50 +    <title>Nozioni di base sui template</title>
    2.51 +
    2.52 +    <para id="x_582">Nella sua forma più semplice, un template Mercurial è un frammento di testo. Parte del testo non cambia mai, mentre altre parti vengono <emphasis>espanse</emphasis>, o sostituite con nuovo testo, quando è necessario.</para>
    2.53 +
    2.54 +    <para id="x_583">Prima di continuare, diamo un'altra occhiata al semplice esempio del normale output di Mercurial</para>
    2.55 +
    2.56 +    &interaction.template.simple.normal;
    2.57 +
    2.58 +    <para id="x_584">Ora, eseguiamo lo stesso comando, ma usando un template per cambiare il suo output.</para>
    2.59 +
    2.60 +    &interaction.template.simple.simplest;
    2.61 +
    2.62 +    <para id="x_585">Questo esempio illustra il template più semplice possibile, composto solo da un frammento di testo statico stampato una volta per ogni changeset. L'opzione <option role="hg-opt-log">--template</option> per il comando <command role="hg-cmd">hg log</command> dice a Mercurial di usare il testo dato come template nel stampare ogni changeset.</para>
    2.63 +
    2.64 +    <para id="x_586">Notate che la stringa di template appena usata termina con il testo <quote><literal>\n</literal></quote>. Questa è una <emphasis>sequenza di escape</emphasis> che dice a Mercurial di stampare una carattere di nuova riga alla fine di ogni elemento di template. Se omettete questa nuova riga, Mercurial mostrerà ogni frammento di output uno dietro l'altro. Leggete la <xref linkend="sec:template:escape"/> per maggiori dettagli sulle sequenze di escape.</para>
    2.65 +
    2.66 +    <para id="x_587">Un template che stampa una stringa di testo fissata tutte le volte non è molto utile, perciò proviamo qualcosa di un po' più complesso.</para>
    2.67 +
    2.68 +    &interaction.template.simple.simplesub;
    2.69 +
    2.70 +    <para id="x_588">Come potete vedere, la stringa <quote><literal>{desc}</literal></quote> nel template è stata sostituita nell'output con la descrizione di ogni changeset. Ogni volta che Mercurial trova testo racchiuso tra parentesi graffe (<quote><literal>{</literal></quote> e <quote><literal>}</literal></quote>), proverà a sostituire le parentesi e il testo con l'espansione di qualunque cosa vi sia contenuta. Per stampare una parentesi graffa letterale, dovete effettuarne l'escape, come descritto nella <xref linkend="sec:template:escape"/>.</para>
    2.71 +  </sect1>
    2.72 +
    2.73 +  <sect1 id="sec:template:keyword">
    2.74 +    <title>Parole chiave comuni nei template</title>
    2.75 +
    2.76 +    <para id="x_589">Potete cominciare immediatamente a scrivere semplici template usando le seguenti parole chiave.</para>
    2.77 +
    2.78 +    <itemizedlist>
    2.79 +      <listitem><para id="x_58a"><literal role="template-keyword">author</literal>: stringa. Il nome non modificato dell'autore del changeset.</para>
    2.80 +      </listitem>
    2.81 +      <listitem><para id="x_58b"><literal role="template-keyword">branches</literal>: stringa. Il nome del ramo su cui il changeset è stato inserito. Sarà vuoto se il nome del branch è <literal>default</literal>.</para>
    2.82 +      </listitem>
    2.83 +      <listitem><para id="x_58c"><literal role="template-keyword">date</literal>: informazioni di data. La data in cui il changeset è stato inserito. Questa informazione <emphasis>non</emphasis> è pensata per essere letta dalle persone; dovete passarla attraverso un filtro che la presenterà in maniera appropriata. Leggete la <xref linkend="sec:template:filter"/> per maggiori informazioni sui filtri. La data viene espressa come una coppia di numeri. Il primo numero è una marcatura temporale che segue lo Unix UTC (e indica il numero di secondi trascorsi dal 1° gennaio 1970); il secondo è la differenza tra la zona temporale dell'autore del commit e l'UTC, in secondi.</para>
    2.84 +      </listitem>
    2.85 +      <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>: stringa. Il testo della descrizione del changeset.</para>
    2.86 +      </listitem>
    2.87 +      <listitem><para id="x_58e"><literal role="template-keyword">files</literal>: lista di stringhe. Tutti i file modificati, aggiunti, o rimossi da questo changeset.</para>
    2.88 +      </listitem>
    2.89 +      <listitem><para id="x_58f"><literal role="template-keyword">file_adds</literal>: lista di stringhe. I file aggiunti da questo changeset.</para>
    2.90 +      </listitem>
    2.91 +      <listitem><para id="x_590"><literal role="template-keyword">file_dels</literal>: lista di stringhe. I file rimossi da questo changeset.</para>
    2.92 +      </listitem>
    2.93 +      <listitem><para id="x_591"><literal role="template-keyword">node</literal>: stringa. L'hash di identificazione del changeset, sotto forma di una stringa esadecimale di 40 caratteri.</para>
    2.94 +      </listitem>
    2.95 +      <listitem><para id="x_592"><literal role="template-keyword">parents</literal>: lista di stringhe. I genitori del changeset.</para>
    2.96 +      </listitem>
    2.97 +      <listitem><para id="x_593"><literal role="template-keyword">rev</literal>: intero. Il numero di revisione del changeset locale per il repository.</para>
    2.98 +      </listitem>
    2.99 +      <listitem><para id="x_594"><literal role="template-keyword">tags</literal>: lista di stringhe. Qualsiasi etichetta associata al changeset.</para>
   2.100 +      </listitem>
   2.101 +    </itemizedlist>
   2.102 +
   2.103 +    <para id="x_595">Alcuni semplici esperimenti ci mostreranno cosa aspettarci quando usiamo queste parole chiave. Potete vederne i risultati qui di seguito.</para>
   2.104 +
   2.105 +    &interaction.template.simple.keywords;
   2.106 +
   2.107 +    <para id="x_596">Come abbiamo notato prima, la parola chiave per la data non produce un output in forma leggibile, così dobbiamo trattarla in maniera speciale. Questo implica l'uso dei <emphasis>filtri</emphasis>, che verranno trattati in maniera più approfondita nella <xref linkend="sec:template:filter"/>.</para>
   2.108 +
   2.109 +    &interaction.template.simple.datekeyword;
   2.110 +  </sect1>
   2.111 +
   2.112 +  <sect1 id="sec:template:escape">
   2.113 +    <title>Sequenze di escape</title>
   2.114 +
   2.115 +    <para id="x_597">Il motore di template di Mercurial riconosce le sequenze di escape più comunemente usate nelle stringhe. Quando vede un carattere di backslash (<quote><literal>\</literal></quote>), guarda il carattere successivo e sostituisce i due caratteri con un unico rimpiazzo, come descritto qui di seguito.</para>
   2.116 +
   2.117 +    <itemizedlist>
   2.118 +      <listitem><para id="x_598"><literal>\</literal>:
   2.119 +	  backslash, <quote><literal>\</literal></quote>, ASCII
   2.120 +	  134.</para>
   2.121 +      </listitem>
   2.122 +      <listitem><para id="x_599"><literal>\n</literal>: nuova riga,
   2.123 +	  ASCII 12.</para>
   2.124 +      </listitem>
   2.125 +      <listitem><para id="x_59a"><literal>\r</literal>: ritorno a capo, ASCII 15.</para>
   2.126 +      </listitem>
   2.127 +      <listitem><para id="x_59b"><literal>\t</literal>: tabulazione, ASCII
   2.128 +	  11.</para>
   2.129 +      </listitem>
   2.130 +      <listitem><para id="x_59c"><literal>\v</literal>: tabulazione verticale, ASCII 13.</para>
   2.131 +      </listitem>
   2.132 +      <listitem><para id="x_59d"><literal>\{</literal>: parentesi graffa aperta, <quote><literal>{</literal></quote>, ASCII
   2.133 +	  173.</para>
   2.134 +      </listitem>
   2.135 +      <listitem><para id="x_59e"><literal>\}</literal>: parentesi graffa chusa, <quote><literal>}</literal></quote>, ASCII
   2.136 +	  175.</para>
   2.137 +      </listitem></itemizedlist>
   2.138 +
   2.139 +    <para id="x_59f">Come appena indicato, se volete che l'espansione di un template contenga una carattere <quote><literal>\</literal></quote>, <quote><literal>{</literal></quote>, o <quote><literal>{</literal></quote> letterale, dovete effettuarne l'escape.</para>
   2.140 +  </sect1>
   2.141 +
   2.142 +  <sect1 id="sec:template:filter">
   2.143 +    <title>Filtrare le parole chiave per modificarne i risultati</title>
   2.144 +
   2.145 +    <para id="x_5a0">Alcuni dei risultati dell'espansione dei template non sono immediatamente facili da usare. Mercurial vi permette di specificare una catena opzionale di <emphasis>filtri</emphasis> per modificare il risultato dell'espansione di una parola chiave. Avete già visto un filtro comune, <literal role="template-kw-filt-date">isodate</literal>, precedentemente in azione per rendere leggibile una data.</para>
   2.146 +
   2.147 +    <para id="x_5a1">Qui di seguito viene presentata una lista dei filtri più comunemente usati che Mercurial supporta. Mentre alcuni filtri possono essere applicati a qualsiasi testo, altri possono essere usati solo in circostanze specifiche. Il nome di ogni filtro è seguito prima da una indicazione su dove può essere usato e poi da una descrizione dei suoi effetti.</para>
   2.148 +
   2.149 +    <itemizedlist>
   2.150 +      <listitem><para id="x_5a2"><literal role="template-filter">addbreaks</literal>: qualsiasi testo. Aggiunge un elemento XHTML <quote><literal>&lt;br/&gt;</literal></quote> prima della fine di ogni riga tranne l'ultima. Per esempio, <quote><literal>foo\nbar</literal></quote> diventa <quote><literal>foo&lt;br/&gt;\nbar</literal></quote>.</para>
   2.151 +      </listitem>
   2.152 +      <listitem><para id="x_5a3"><literal role="template-kw-filt-date">age</literal>: parola chiave <literal role="template-keyword">date</literal>. Rappresenta l'età della data, relativa all'ora corrente. Produce stringhe come <quote><literal>10 minutes</literal></quote>.</para>
   2.153 +      </listitem>
   2.154 +      <listitem><para id="x_5a4"><literal role="template-filter">basename</literal>: qualsiasi testo, ma utile soprattutto per la parola chiave <literal role="template-keyword">files</literal> e relative. Tratta il testo come un percorso e restituisce il nome di base. Per esempio, <quote><literal>foo/bar/baz</literal></quote> diventa <quote><literal>baz</literal></quote>.</para>
   2.155 +      </listitem>
   2.156 +      <listitem><para id="x_5a5"><literal role="template-kw-filt-date">date</literal>: parola chiave <literal role="template-keyword">date</literal>. Presenta una data in un formato simile al comando Unix <literal role="template-keyword">date</literal>, ma includendo la zona temporale. Produce stringhe come <quote><literal>Mon Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
   2.157 +      </listitem>
   2.158 +      <listitem><para id="x_5a6"><literal role="template-kw-filt-author">domain</literal>: qualsiasi testo, ma utile soprattutto per la parola chiave <literal role="template-keyword">author</literal>. Trova la prima stringa che somiglia a un indirizzo email e ne estrae il componente del dominio. Per esempio, <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> diventa <quote><literal>serpentine.com</literal></quote>.</para>
   2.159 +      </listitem>
   2.160 +      <listitem><para id="x_5a7"><literal role="template-kw-filt-author">email</literal>: qualsiasi testo, ma utile soprattutto per la parola chiave <literal role="template-keyword">author</literal>. Estrae la prima stringa che somiglia a un indirizzo email. Per esempio, <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> diventa <quote><literal>bos@serpentine.com</literal></quote>.</para>
   2.161 +      </listitem>
   2.162 +      <listitem><para id="x_5a8"><literal role="template-filter">escape</literal>: qualsiasi testo. Sostituisce i caratteri speciali XML/XHTML <quote><literal>&amp;</literal></quote>, <quote><literal>&lt;</literal></quote> e <quote><literal>&gt;</literal></quote> con entità XML.</para>
   2.163 +      </listitem>
   2.164 +      <listitem><para id="x_5a9"><literal role="template-filter">fill68</literal>: qualsiasi testo. Manda a capo il testo per farlo stare in 68 colonne. Questo è utile prima di passare il testo attraverso al filtro <literal role="template-filter">tabindent</literal>, se volete che stia ancora in una finestra di 80 colonne con caratteri a spaziatura fissa.</para>
   2.165 +      </listitem>
   2.166 +      <listitem><para id="x_5aa"><literal role="template-filter">fill76</literal>: qualsiasi testo. Manda a capo il testo per farlo stare in 76 colonne.</para>
   2.167 +      </listitem>
   2.168 +      <listitem><para id="x_5ab"><literal role="template-filter">firstline</literal>: qualsiasi testo. Produce la prima riga del testo, senza alcun carattere di nuova riga alla fine.</para>
   2.169 +      </listitem>
   2.170 +      <listitem><para id="x_5ac"><literal role="template-kw-filt-date">hgdate</literal>: parola chiave <literal role="template-keyword">date</literal>. Rappresenta la data come una coppia di numeri leggibili. Produce una stringa come <quote><literal>1157407993 25200</literal></quote>.</para>
   2.171 +      </listitem>
   2.172 +      <listitem><para id="x_5ad"><literal role="template-kw-filt-date">isodate</literal>: parola chiave <literal role="template-keyword">date</literal>. Rappresenta una data come stringa di testo in formato ISO 8601. Produce una stringa come <quote><literal>2006-09-04 15:13:13 -0700</literal></quote>.</para>
   2.173 +      </listitem>
   2.174 +      <listitem><para id="x_5ae"><literal role="template-filter">obfuscate</literal>: qualsiasi testo, ma utile soprattutto per la parola chiave <literal role="template-keyword">author</literal>. Riproduce il testo in ingresso rappresentandolo come una sequenza di entità XML. Questo è utile per battere alcuni #spambot# particolarmente stupidi che effettuano lo #screen-scraping# per raccogliere indirizzi email.</para>
   2.175 +      </listitem>
   2.176 +      <listitem><para id="x_5af"><literal role="template-kw-filt-author">person</literal>: qualsiasi testo, ma utili soprattutto per la parola chiave <literal role="template-keyword">author</literal>. Produce il testo prima di un indirizzo email. Per esempio, <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> diventa <quote><literal>Bryan O'Sullivan</literal></quote>.</para>
   2.177 +      </listitem>
   2.178 +      <listitem><para id="x_5b0"><literal role="template-kw-filt-date">rfc822date</literal>: parola chiave <literal role="template-keyword">date</literal>. Rappresenta una data usando lo stesso formato impiegato nelle intestazioni email. Produce una stringa come <quote><literal>Mon, 04 Sep 2006 15:13:13 -0700</literal></quote>.</para>
   2.179 +      </listitem>
   2.180 +      <listitem><para id="x_5b1"><literal role="template-kw-filt-node">short</literal>: hash di changeset. Produce la forma breve di un hash di changeset, i.e. una stringa esadecimale di 12 caratteri.</para>
   2.181 +      </listitem>
   2.182 +      <listitem><para id="x_5b2"><literal role="template-kw-filt-date">shortdate</literal>: parola chiave <literal role="template-keyword">date</literal>. Rappresenta l'anno, il mese e il giorno della data. Produce una stringa come <quote><literal>2006-09-04</literal></quote>.</para>
   2.183 +      </listitem>
   2.184 +      <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>: qualsiasi testo. Rimuove lo spazio bianco all'inizio e alla fine di una stringa.</para>
   2.185 +      </listitem>
   2.186 +      <listitem><para id="x_5b4"><literal role="template-filter">tabindent</literal>: qualsiasi testo. Produce il testo, facendo cominciare ogni riga tranne la prima con un carattere di tabulazione.</para>
   2.187 +      </listitem>
   2.188 +      <listitem><para id="x_5b5"><literal role="template-filter">urlescape</literal>: qualsiasi testo. Effettua l'escape di tutti i caratteri che sono considerati <quote>speciali</quote> dai riconoscitori di URL. Per esempio, <literal>foo bar</literal> diventa <literal>foo%20bar</literal>.</para>
   2.189 +      </listitem>
   2.190 +      <listitem><para id="x_5b6"><literal role="template-kw-filt-author">user</literal>: qualsiasi testo, ma utile soprattutto per la parola chiave <literal role="template-keyword">author</literal>. Restituisce la porzione dell'<quote>utente</quote> di un indirizzo email. Per esempio <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> diventa <quote><literal>bos</literal></quote>.</para>
   2.191 +      </listitem>
   2.192 +    </itemizedlist>
   2.193 +
   2.194 +    &interaction.template.simple.manyfilters;
   2.195 +
   2.196 +    <note>
   2.197 +      <para id="x_5b7">Se provate ad applicare un filtro a un frammeto di dati che non può elaborare, Mercurial fallirà e stamperà una eccezione Python. Per esempio, provare a utilizzare l'output della parola chiave <literal role="template-keyword">desc</literal> con il filtro <literal role="template-kw-filt-date">isodate</literal> non è una buona idea.</para>
   2.198 +    </note>
   2.199 +
   2.200 +    <sect2>
   2.201 +      <title>Combinare i filtri</title>
   2.202 +
   2.203 +      <para id="x_5b8">&Egrave; facile combinare filtri per produrre un output della forma che preferite. La seguente catena di filtri ripulisce una descrizione, poi si assicura che stia tranquillamente in 68 colonne, poi la indenta ulteriormente di 8 caratteri (almeno sui sistemi di tipo Unix, dove una tabulazione è convenzionalmente larga 8 caratteri).</para>
   2.204 +
   2.205 +      &interaction.template.simple.combine;
   2.206 +
   2.207 +      <para id="x_5b9">Notate l'uso di <quote><literal>\t</literal></quote> (un carattere di tabulazione) nel template per forzare la prima riga a essere indentata; questo è necessario dato che <literal role="template-keyword">tabindent</literal> indenta tutte le righe <emphasis>tranne</emphasis> la prima.</para>
   2.208 +
   2.209 +      <para id="x_5ba">Tenete a mente che l'ordine dei filtri in una catena è significativo. Il primo filtro viene applicato al risultato della parola chiave; il secondo al risultato del primo filtro; e così via. Per esempio, usare <literal>fill68|tabindent</literal> dà risultati molto diversi da <literal>tabindent|fill68</literal>.</para>
   2.210 +    </sect2>
   2.211 +  </sect1>
   2.212 +
   2.213 +  <sect1>
   2.214 +    <title>Dai template agil stili</title>
   2.215 +
   2.216 +    <para id="x_5bb">Un template a riga di comando fornisce un modo veloce e semplice per formattare un certo output. I template possono diventare prolissi, però, e quindi è utile essere in grado di dare un nome a un template. Un file di stile è un template con un nome, memorizzato in un file.</para>
   2.217 +
   2.218 +    <para id="x_5bc">Più di questo, usare un file di stile sblocca la potenza del motore di template di Mercurial in modi che non sono possibili usando l'opzione <option role="hg-opt-log">--template</option> a riga di comando.</para>
   2.219 +
   2.220 +    <sect2>
   2.221 +      <title>Il più semplice dei file di stile</title>
   2.222 +
   2.223 +      <para id="x_5bd">Il nostro semplice file di stile contiene solo una riga:</para>
   2.224 +
   2.225 +      &interaction.template.simple.rev;
   2.226 +
   2.227 +      <para id="x_5be">Questo dice a Mercurial, <quote>se stai stampando un changeset, usa il testo sulla destra come template</quote>.</para>
   2.228 +    </sect2>
   2.229 +
   2.230 +    <sect2>
   2.231 +      <title>La sintassi dei file di stile</title>
   2.232 +
   2.233 +      <para id="x_5bf">Le regole della sintassi per un file di stile sono semplici.</para>
   2.234 +
   2.235 +      <itemizedlist>
   2.236 +	<listitem><para id="x_5c0">Il file viene elaborato una riga alla volta.</para>
   2.237 +	</listitem>
   2.238 +	<listitem><para id="x_5c1">Gli spazi bianchi all'inizio e alla fine di una riga vengono ignorati.</para>
   2.239 +	</listitem>
   2.240 +	<listitem><para id="x_5c2">Le righe vuote vengono saltate.</para>
   2.241 +	</listitem>
   2.242 +	<listitem><para id="x_5c3">Se una riga comincia con un carattere <quote><literal>#</literal></quote> o <quote><literal>;</literal></quote>, l'intera riga viene trattata come un commento e saltata come se fosse vuota.</para>
   2.243 +	</listitem>
   2.244 +	<listitem><para id="x_5c4">Una riga comincia con una parola chiave, che deve cominciare con un carattere alfabetico o di sottolineatura e può contenere successivamente qualsiasi carattere alfanumerico o di sottolineatura. (Nella notazione per le espressioni regolari, una parola chiave deve corrispondere a <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
   2.245 +	</listitem>
   2.246 +	<listitem><para id="x_5c5">L'elemento successivo deve essere un carattere <quote><literal>=</literal></quote>, che può essere preceduto o seguito da una quantità arbitraria di spazio bianco.</para>
   2.247 +	</listitem>
   2.248 +	<listitem><para id="x_5c6">Se il resto della riga comincia e finisce con caratteri di apice o virgolette corrispondenti, viene trattato come il corpo di un template.</para>
   2.249 +	</listitem>
   2.250 +	<listitem><para id="x_5c7">Se il resto della riga <emphasis>non</emphasis> comincia con caratteri di apice o virgolette, è trattato come il nome di un file i cui contenuti verranno letti e usati come il corpo di un template.</para>
   2.251 +	</listitem></itemizedlist>
   2.252 +    </sect2>
   2.253 +  </sect1>
   2.254 +
   2.255 +  <sect1>
   2.256 +    <title>Esempi di file di stile</title>
   2.257 +
   2.258 +    <para id="x_5c8">Per illustrare come scrivere un file di stile, ne costruiremo alcuni esempi. Piuttosto che fornire un file di stile completo e camminarci attraverso, replicheremo il classico processo di sviluppo di un file di stile cominciando con qualcosa di molto semplice e cammninando attraverso una serie di esempi successivi più completi.</para>
   2.259 +
   2.260 +    <sect2>
   2.261 +      <title>Identificare errori in un file di stile</title>
   2.262 +
   2.263 +      <para id="x_5c9">Se Mercurial incontra un problema in un file di stile su cui state lavorando, stampa uno stringato messaggio di errore che, una volta che avete scoperto cosa significa, è in effetti piuttosto utile.</para>
   2.264 +
   2.265 +      &interaction.template.svnstyle.syntax.input;
   2.266 +
   2.267 +      <para id="x_5ca">Notate che <filename>broken.style</filename> tenta di definire una parola chiave <literal>changeset</literal>, ma dimentica di darle un qualsiasi contenuto. Quando gli si chiede di usare questo file di stile, Mercurial si lamenta prontamente.</para>
   2.268 +
   2.269 +      &interaction.template.svnstyle.syntax.error;
   2.270 +
   2.271 +      <para id="x_5cb">Questo messaggio di errore sembra minaccioso, ma non è troppo difficile da seguire.</para>
   2.272 +
   2.273 +      <itemizedlist>
   2.274 +	<listitem><para id="x_5cc">Il primo componente è semplicemente il modo che Mercurial ha di dire <quote>gliela dò su</quote>.</para>
   2.275 +	  <programlisting>___abort___: broken.style:1: parse error</programlisting>
   2.276 +	</listitem>
   2.277 +	<listitem><para id="x_5cd">Successivamente arriva il nome del file di stile che contiene l'errore.</para>
   2.278 +	  <programlisting>abort: ___broken.style___:1: parse error</programlisting>
   2.279 +	</listitem>
   2.280 +	<listitem><para id="x_5ce">Il nome del file è seguito dal numero di riga dove l'errore è stato incontrato.</para>
   2.281 +	  <programlisting>abort: broken.style:___1___: parse error</programlisting>
   2.282 +	</listitem>
   2.283 +	<listitem><para id="x_5cf">Infine, viene fornita una descrizione di quello che è andato storto.</para>
   2.284 +	  <programlisting>abort: broken.style:1: ___parse error___</programlisting>
   2.285 +	</listitem>
   2.286 +	<listitem><para id="x_5d0">La descrizione del problema non è sempre chiara (come in questo caso), ma anche quando è criptica, è quasi sempre elementare inspezionare visivamente la riga del file di stile che contiene il problema e vedere cosa c'è di sbagliato.</para>
   2.287 +	</listitem>
   2.288 +      </itemizedlist>
   2.289 +    </sect2>
   2.290 +
   2.291 +    <sect2>
   2.292 +      <title>Identificare univocamente un repository</title>
   2.293 +
   2.294 +      <para id="x_5d1">Se volete essere in grado di identificare un repository Mercurial in maniera <quote>abbastanza univoca</quote> usando una breve stringa come identificatore, potete usare la prima revisione contenuta nel repository.</para>
   2.295 +
   2.296 +      &interaction.template.svnstyle.id;
   2.297 +
   2.298 +      <para id="x_5d2">&Egrave; molto probabile che questo identificatore siaunico, quindi si rivela utile in molti casi. Ci sono alcune avvertenze.</para>
   2.299 +      <itemizedlist>
   2.300 +	<listitem><para id="x_5d3">Non funzionerà in un repository completamente vuoto, perché un tale repository non possiede la revisione zero.</para>
   2.301 +	</listitem>
   2.302 +	<listitem><para id="x_5d4">Non funzionerà nemmeno nel caso (estremamente raro) in cui un repository è l'unione di due o più repository precedentemente indipendenti che avete ancora in giro da qualche parte.</para>
   2.303 +	</listitem></itemizedlist>
   2.304 +      <para id="x_5d5">Ecco alcuni usi che potete fare di questo identificatore:</para>
   2.305 +      <itemizedlist>
   2.306 +	<listitem><para id="x_5d6">come chiave nella tabella di un datavase che gestisce i repository presenti su un server.</para>
   2.307 +	</listitem>
   2.308 +	<listitem><para id="x_5d7">come metà di una tupla {<emphasis>identificatore di repository</emphasis>, <emphasis>identificatore di revisione</emphasis>}. Salvate questa informazione da qualche parte quando esguite un assemblaggio automatico o un'altra attività simile, in modo che possiate <quote>rieseguire</quote> l'assemblaggio in seguito se necessario.</para>
   2.309 +	</listitem>
   2.310 +      </itemizedlist>
   2.311 +    </sect2>
   2.312 +
   2.313 +    <sect2>
   2.314 +      <title>Elencare file su più righe</title>
   2.315 +
   2.316 +      <para id="x_714">Supponete di voler elencare i file modificati da un changeset uno per riga, con una piccola indentazione prima di ogni nome di file.</para>
   2.317 +
   2.318 +      &interaction.ch10-multiline.go;
   2.319 +    </sect2>
   2.320 +
   2.321 +    <sect2>
   2.322 +      <title>Imitare l'output di Subversion</title>
   2.323 +
   2.324 +      <para id="x_5d8">Proviamo a emulare il formato di output predefinito usato da un altro strumento di controllo di revisione, Subversion.</para>
   2.325 +
   2.326 +      &interaction.template.svnstyle.short;
   2.327 +
   2.328 +      <para id="x_5d9">Dato che lo stile di output di Subversion è abbastanza semplice, è facile copiare e incollare un pezzo del suo output in un file e rimpiazzare il testo prodotto da Subversion con i valori di template che vorremmo vedere espansi.</para>
   2.329 +
   2.330 +      &interaction.template.svnstyle.template;
   2.331 +
   2.332 +      <para id="x_5da">Ci sono alcuni modi in cui questo template si discosta dall'output prodotto da Subversion.</para>
   2.333 +      <itemizedlist>
   2.334 +	<listitem><para id="x_5db">Subversion stampa una data <quote>leggibile</quote> (il <quote><literal>Wed, 27 Sep 2006</literal></quote> nel risultato dell'esempio precedente) tra parentesi. Il motore di template di Mercurial non fornisce un modo per visualizzare una data in questo formato senza stampare anche l'orario e la zona temporale.</para>
   2.335 +	</listitem>
   2.336 +	<listitem><para id="x_5dc">Emuliamo la stampa da parte di Subversion di righe <quote>separatrici</quote> piene di caratteri <quote><literal>-</literal></quote> concludendo il template con una riga di quel tipo. Usiamo la parola chiave <literal role="template-keyword">header</literal> del motore di template per stampare una riga separatrice come la prima riga di output (vedete più avanti), quindi ottenendo un output simile a quello di Subversion.</para>
   2.337 +	</listitem>
   2.338 +	<listitem><para id="x_5dd">L'output di Subversion include nell'intestazione il conteggio del numero di righe del messaggio di commit. Non possiamo replicare questa caratteristica in Mercurial, poiché attualmente il motore di template non fornisce un filtro che conti il numero di righe generate dal template.</para>
   2.339 +	</listitem></itemizedlist>
   2.340 +      <para id="x_5de">Non mi ci sono voluti più di uno o due minuti di lavoro per sostituire il testo letterale da un esempio dell'output di Subversion con alcune parole chiave e alcuni filtri per ottenere il template appena visto. Il file di stile fa semplicemente riferimento al template.</para>
   2.341 +
   2.342 +      &interaction.template.svnstyle.style;
   2.343 +
   2.344 +      <para id="x_5df">Avremmo potuto includere il testo del file di template direttamente nel file di stile, circondandolo con virgolette e rimpiazzando le nuove righe con sequenze <quote><literal>\n</literal></quote>, ma questo avrebbe reso il file di stile troppo difficile da leggere. La leggibilità è una buona guida quando state cercando di decidere se un certo testo appartiene a un file di stile o a un file di template a cui il file di stile fa riferimento. Nel caso il file di stile vi sembrasse troppo grande o disordinato se inserite un frammento letterale di testo, spostatelo invece in un template.</para>
   2.345 +    </sect2>
   2.346 +  </sect1>
   2.347 +</chapter>