about.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: e8ac70bf549a723cb36465667a6109d9933b8619 Maintainer: garak Status: ready -->
<!-- Reviewed: no -->
<appendix xml:id="about" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Informazioni sul manuale</title>

 <sect1 xml:id="about.formats">
  <title>Formati</title>
  <para>
   Il manuale di PHP è distribuito in diversi formati. Questi formati possono
   essere divisi in due gruppi: formati leggibili online e pacchetti scaricabili.
  </para>
  <note>
   <para>
    Alcuni editori hanno reso disponibile una versione di questo manuale adatta
    alla stampa. Noi sconsigliamo questo tipo di manuali, in quanto tendono a
    diventare obsoleti molto rapidamente.
   </para>
  </note>
  <para>
   Si può leggere il manuale online sul <link xlink:href="&url.php;">sito PHP.net</link>.
   La versione online del manuale PHP ha attualmente due
   stylesheet <acronym>CSS</acronym>, uno per il web e uno per la stampa.
  </para>
  <para>
   Due vantaggi del manuale online sulla maggior parte dei formati offline
   sono l'integrazione dei <link linkend="about.notes">contributi degli utenti</link>
   e le <link xlink:href="&url.php.urlhowto;">scorciatoie URL</link> che permettono
   di ottenere rapidamente la pagina del manuale desiderata. Ovviamente,
   per poter visualizzare il manuale online, si deve essere collegati ad internet.
  </para>
  <para>
   Ci sono diversi tipi di manuale scaricabili, e il formato più appropriato
   dipende dal tipo di sistema operativo utilizzato e dal
   personale modo di leggere. Per informazioni su come il manuale viene generato
   in così tanti formati, leggere la sezione <link linkend="about.generate">'Come
   generiamo i formati'</link> di questa appendice.
  </para>
  <para>
   Il formato più adatto a diversi tipi di sistemi operativi è l'HTML. Il formato HTML
   è disponibile sia come unica pagina HTML, sia come pacchetto di file univoci per
   ogni sezione (cioè qualche migliaio di file).
   Queste versioni sono fornite compresse, pertanto occorre disporre di utility
   di decompressione per ottenere i file contenuti negli archivi.
  </para>
  <!--
   La versione PDF del manuale PHP è "attualmente" non disponibile. Forse
   esisterà un giorno.
  <para>
   Un altro formato adatto a diversi tipi di sistemi operativi e alla stampa è il
   formato PDF (conosciuto anche come Adobe Acrobat). Ma attenzione! Il manuale
   contiene oltre 2000 pagine e che viene aggiornato e corretto frequentemente.
  </para>
  <note>
   <para>
    Esistono molti programmi in grado di leggere il formato <acronym>PDF</acronym>, come
    <link xlink:href="&url.adobe.acrobat;">Adobe Acrobat Reader</link>.
   </para>
  </note>
  -->
  <para>
   Per le piattaforme Windows, la versione <productname>HTML Help per Windows</productname> del manuale
   fornisce contenuti utilizzabili con le applicazioni
   <productname>HTML Help per Windows</productname>. Questa
   versione è fornita con un motore di ricerca per tutto il contenuto, con un indice completo e con la possibilità di salvare le
   ricerche. Molte versioni di manuale PHP per Windows integrano anche questa
   versione della documentazione, per garantire un accesso più semplice.
   Sono disponibili diversi visualizzatori CHM per Linux. Alcuni esempi:
   <link xlink:href="&url.xchm;">xCHM</link> oppure
   <link xlink:href="&url.gnochm;">GnoCHM</link>.
  </para>
  
  <para>
   Inoltre esiste una <link xlink:href="&url.php.echm;">versione CHM estesa</link>,
   che viene aggiornata con frequenza minore, ma fornisce maggiori caratteristiche.
   È disponibile soltanto su <productname>Microsoft Windows</productname>
   a causa della tecnologia utilizzata per realizzare queste pagine.
  </para>
 </sect1>
 
 <sect1 xml:id="about.notes">
  <title>Contributi degli utenti</title>
  <para>
   I contributi degli utenti giocano un ruolo importante nello sviluppo di questo
   manuale. Possiamo includere questi feedback nel testo principale del manuale
   permettendo agli utenti di contribuire con esempi, avvertimenti e chiarimenti
   riguardo a diversi tipi di browser. I contributi inviati dagli utenti sono
   visibili, così come sono stati inviati, nel formato online del manuale ed in
   alcuni dei formati scaricabili.
  </para>
  <note>
   <para>
    I contributi degli utenti NON sono controllati prima di essere messi online,
    quindi la chiarezza del contenuto, gli esempi di codice o l'esattezza stessa
    dei contributi non puù essere garantita. (E non c'è alcuna garanzia sulla
    qualità o sull'esattezza del testo dello stesso manuale.)
   </para>
  </note>
  <note>
   <para>
    Dal punto di vista della licenza i contributi degli utenti sono
    considerati parte del manuale PHP, e quindi coperti dalla
    stessa licenza che si applica a questa documentazione (Creative Commons Attribution
    al momento). Per maggiori dettagli
    vedere la pagina
    <link linkend="copyright">Copyright del manuale </link>.
   </para>
  </note>
 </sect1>

 <sect1 xml:id="about.prototypes">
   <title>Come leggere la definizione di una funzione (prototipo)</title>
   <para>
    Nel manuale ciascuna funzione è documentata per un rapido riferimento. Conoscendo
    come leggere e capendo il testo si è in grado di apprendere
    PHP molto più facilmente. Piuttosto che appoggiarsi sugli esempi o sul copia e incolla,
    preferirai sicuramente sapere come leggere la definizione di una funzione. Cominciamo:
   </para>
   <note>
    <title>
     Pre-requisito: comprensione di base dei <link linkend="language.types">tipi di variabili</link>
    </title>
    <para>
     Sebbene PHP sia un linguaggio poco tipizzato (loosely typed), è importante avere
     una conoscenza di base delle <link linkend="language.types">tipologie</link> di variabili
     per il loro importante significato.
    </para>
   </note>
   <para>
    La definizione della funzione ci dice quale tipo
    di valore viene <link linkend="functions.returning-values">restituito</link>.
    Utilizziamo la definizione di <function>strlen</function> come nostro primo esempio:
   </para>
   <para>
    <screen role="html">
<![CDATA[
strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Restituisce la lunghezza di una stringa

Descrizione
strlen ( string $string ) : int

Restituisce la lunghezza della stringa data.
]]>
    </screen>
   </para>
   <para>
    <table>
     <title>Spiegazione della definizione di una funzione</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Parte</entry>
         <entry>Descrizione</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>
          strlen
         </entry>
         <entry>
          Nome della funzione.
         </entry>
        </row>
        <row>
         <entry>
          (PHP 4, PHP 5, PHP 7)
         </entry>
         <entry>
          strlen() è disponibile in tutte le versioni di PHP 4, 5 e 7
         </entry>
        </row>
        <row>
         <entry>
          ( string $string )
         </entry>
         <entry>
          Il primo (ed in questo caso unico) parametro/argomento per questa
          funzione si chiama <parameter>string</parameter>, ed è una
          <type>string</type>.
         </entry>
        </row>
        <row>
         <entry>
          int
         </entry>
         <entry>
          Tipo di valore restituito dalla funzione, il quale è un
          <type>int</type> (ovvero la lunghezza di una stringa si misura in
          numeri).
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
    <para>
     Si potrebbe riscrivere la funzione precedente in modo generico:
    </para>
    <para>
     <screen>
<![CDATA[
      function name    ( parameter type   parameter name ) : returned type
]]>
     </screen>
    </para>
    <para>
     Diverse funzioni hanno diversi parametri, tipo <function>in_array</function>.
     Il loro prototipo è:
    </para>
    <para>
     <screen>    
<![CDATA[
      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool
]]>
     </screen>
    </para>
    <para>
     Cosa significa? in_array() restituisce un valore
     <link linkend="language.types.boolean">boolean</link> value, &true; se riesce
     (se il parametro <parameter>needle</parameter> viene trovato in
     <parameter>haystack</parameter>) oppure &false; se fallisce (se il parametro
     <parameter>needle</parameter> non viene trovato in
     <parameter>haystack</parameter>).  Il primo parametro si chiama
     <parameter>needle</parameter> e può essere di diversi
     <link linkend="language.types">tipi</link>, pertanto lo chiameremo
     "<emphasis>mixed</emphasis>".  Questo parametro <parameter>needle</parameter> di tipo mixed
     (che indica che il valore che stiamo cercando) può essere sia un valore scalare (stringa, intero,
     oppure <link linkend="language.types.float">float</link>), sia una
     <link linkend="language.types.array">matrice o array</link>.
     <parameter>haystack</parameter> (che indica la variabile in cui cercare) è il
     secondo parametro. Il terzo parametro <emphasis>opzionale</emphasis> è
     chiamato <parameter>strict</parameter>.  Tutti i parametri opzionali hanno valori
     di default; se il valore di default è sconosciuto, viene mostrato come <literal>?</literal>.  Il manuale
     indica che il valore di default per <parameter>strict</parameter> è il
     boolean &false;.  Vedere le pagine del manuale di ciascuna funzione per i dettagli
     di come funziona.
    </para>
    <para> 
     In aggiunta il simbolo &amp; (ampersand) anteposto ad un parametro di una funzione
     permette al parametro di essere passato per <link linkend="language.references.pass">referenza</link>, come mostrato sotto: 
    </para>
    <para>
     <screen> 
<![CDATA[
       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false
]]>
     </screen>
    </para>
    <para>
     In questo esempio, si può vedere il terzo parametro opzionale <parameter>&amp;$matches</parameter> che verrà
     passato per referenza. 
    </para>
    <para>
     Esistono anche funzioni con complesse informazioni sulla versione PHP. Ad esempio
     la funzione <function>html_entity_decode</function>:
    </para>
    <para>
     <screen>    
<![CDATA[
(PHP 4 >= 4.3.0, PHP 5, PHP 7)
]]>
     </screen>
    </para>
    <para>
     Questo significa che questa funzione è
     disponibile solo a partire dalla release PHP 4.3.0.
    </para>
 </sect1>
 
 <sect1 xml:id="about.phpversions">
  <title>Le versioni di PHP documentate in questo manuale</title>
  <para>
   Questa documentazione contiene informazioni sulle versioni presenti,
   passate e future di PHP. Cambiamenti nel comportamento sono documentati come annotazioni, cronologie e
   testo nelle pagine del manuale. 
   La versione documentata più vecchia è PHP 7.0.0.
  </para>
  <para>
   Quando la documentazione esiste per l'ultima versione in sviluppo (non rilasciata)
   di PHP, verrà etichettata come "disponibile in Git" o "versione in
   sviluppo". E anche se queste modifiche sono pianificate, in rari casi
   possono cambiare.
  </para>
  <para>
   Tutti gli sviluppi sono registrati in Git e possono essere recuperati
   come descritto nella pagina <link xlink:href="&url.php.anongit;">accesso
   anonimo a Git</link>.
  </para>
  <para>
   Il manuale fa riferimento a versioni major, minor e point di PHP.
   Usando PHP <literal>7.3.1</literal> come esempio, il <emphasis>7</emphasis>
   si riferisce alla versione major, <emphasis>3</emphasis> alla minor, e
   <emphasis>1</emphasis> al "point release". Normalmente PHP aggiunge funzionalità
   solo a versioni major e minor, e risolve i bug nelle versioni point. Comunque,
   questa convenzione non è sempre seguita.
  </para>
  <para>
   Si noti che il manuale PHP è scritto al presente, non al futuro,
   anche per funzionalità documentate che non sono ancora disponibili. La ragione di questo
   è che il manuale deve essere stabile nel tempo, e non debba richiedere fastidiose correzioni
   grammaticali ad ogni nuovo rilascio di PHP.
  </para>
  <para>
   In diverse occasioni il manuale di PHP presenta dei "valori di default" per le configurazioni di PHP. Questi
   valori sono basati su come PHP si comporta senza un file di configurazione &php.ini;,
   quindi questi valori possono essere differenti da quelli trovati nei file
   <filename>php.ini-development</filename> e <filename>php.ini-production</filename>.
   Inoltre essi si riferiscono all'ultima versione di PHP, anche se le cronologie
   non riportano valori antecedenti. Vedere la pagina di appendice <link linkend="ini.list">appendice sulle direttive PHP
   </link> per dettagli e modifiche su questi valori.
  </para>
 </sect1>
   
 <sect1 xml:id="about.more">
  <title>Come trovare più informazioni su PHP</title>
  <para>
   Lo scopo di questo manuale non è quello di fornire istruzioni sulla pratica
   in generale della programmazione. Gli sviluppatori principianti o alle prime armi
   possono trovare difficile apprendere a programmare in PHP usando
   solo questo manuale. È consigliabile cercare un testo più orientato
   ai principianti.
  </para>
  <para>
   Ci sono diverse mailing list attive per discutere su tutti gli aspetti del
   programmare con PHP. Se si ha un problema, si utilizzino queste liste.
   Per le opzioni di supporto, tra cui le mailing list, vedere <link
   xlink:href="&url.php.support;">la pagina di supporto di PHP.net</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.howtohelp">
  <title>Come aiutare a migliorare la documentazione</title>
  <para>
   Ci sono tanti modi per aiutarci a migliorare questa documentazione.
  </para>
  <para>
   Se si trova un errore all'interno di questo manuale, in qualsiasi lingua esso sia,
   comunicarlo usando il sistema di tracciamento dei problemi del rispettivo repository della lingua su <link xlink:href="&url.php.git;">&url.php.git;</link>; 
   ad esempio, gli errori nel manuale in inglese dovrebbero essere segnalati su 
   <link xlink:href="&url.php.git;doc-en/issues">&url.php.git;doc-en/issues</link>.
   Allo stesso indirizzo si possono anche segnalare problemi relativi ad uno specifico
   formato di manuale.
  </para>
  <note>
   <para>
    Si prega di non abusare del sistema di tracciamento spedendo richieste
    di aiuto. Se si è in difficoltà, usare una delle varie 
    <link xlink:href="&url.php.support;">opzioni di supporto</link>.
   </para>
  </note>
  <para>
   Contribuendo con l'invio di note, gli utilizzatori possono fornire ulteriori esempi, avvertimenti e
   chiarificazioni per altri lettori. Si prega di non segnalare bug usando
   il sistema di invio delle note. Per sapere di più sul sistema di invio delle note
   puoi leggere la sezione <link linkend="about.notes">Sistema di invio delle note</link>.
  </para>
  <para>
   È anche possibile inviare pull request al
   <link xlink:href="&url.php.git.mirror;doc-en">repository Github mirror della documentazione</link>.
  </para>
  <para>
   Il manuale PHP è tradotto in parecchie lingue. Se si conosce l'inglese e
   una lingua straniera, si può lavorare con il team di traduzione per
   migliorare il manuale PHP. Per maggiori informazioni su come iniziare una nuova
   traduzione, o aiutare un progetto di traduzione, leggere
   <link xlink:href="&url.php.dochowto;">&url.php.dochowto;</link>.
  </para>
  <para>
   Il progetto di documentazione PHP usa un canale IRC frequentato da
   molti autori del manuale. Ci si può connettere a <literal>#php.doc</literal> su
   <literal>irc.efnet.org</literal> per discutere su come migliorare
   la documentazione.
  </para>
 </sect1>

 <sect1 xml:id="about.generate">
  <title>Come generiamo i diversi formati</title>
  <para>
   Questo manuale è scritto in <acronym>XML</acronym> usando il <link
   xlink:href="&url.docbook.xml;">DocBook XML DTD</link> e usando <link
   xlink:href="&url.phd;"><acronym>PhD</acronym></link> (il formattatore
   DocBook basato su PHP) per la sua manutenzione e formattazione.
  </para>
  <para>
   Usare l'<acronym>XML</acronym> come formato originale rende possibile
   generare diversi tipi di formato partendo da un unico sorgente,
   mantenendo solo un sorgente per tutti i diversi formati.
   Lo strumento utilizzato per formattare le versioni è <link
   xlink:href="&url.phd;">PhD</link>.
   Per generare la versione <productname>HTML Help per Windows</productname> usiamo
   <link xlink:href="&url.winhelp;">Microsoft HTML Help Workshop</link> e, ovviamente,
   anche PHP stesso per qualche conversione addizionale
   e per la formattazione.
  </para>
  <para>
   Il manuale PHP è generato in diverse lingue e formati, vedere
   <link xlink:href="&url.php.docs;">&url.php.docs;</link> per ulteriori dettagli.
   Il codice sorgente in <acronym>XML</acronym> può essere scaricato da git e
   visualizzato su <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>.
  </para>
 </sect1>

 <sect1 xml:id="about.translations">
  <title>Traduzioni</title>
  <para>
   Il manuale PHP è disponibile non solo in vari formati, ma
   anche in varie lingue. Il testo originale è scritto
   in inglese, mentre gruppi di persone da tutto il mondo
   si occupano di tradurlo nelle rispettive lingue.
   Se non esiste la traduzione per un specifico capitolo o funzione
   la procedura di compila del manuale utilizza la
   versione inglese del capitolo.
  </para>
  <para>
   Le persone che si occupano della traduzioni iniziano dal codice <acronym>XML</acronym>
   disponibile da <link xlink:href="&url.php.git.mirror;doc-en">&url.php.git.mirror;doc-en</link>
   e da questo partono per la traduzione nella propria lingua.
   <emphasis>Non si usano</emphasis> le versioni generate (come
   <acronym>HTML</acronym> o il testo normale) in quanto è il sistema di compilazione che si occupa
   della conversione da <acronym>XML</acronym> ai vari formati
   leggibili.
  </para>
  <note>
   <para>
    Se si desidera aiutare la traduzione nella propria lingua,
    occorre entrare in contatto con il gruppo di traduzione/documentazione
    tramite la mailing list phpdoc: inviare una mail vuota a  <link
    xlink:href="mailto:&email.php.doc.subscribe;">&email.php.doc.subscribe;</link>.
    L'indirizzo della mailing list è <literal>&email.php.doc;</literal>. Indicare nel
    messaggio che si è interessati alla traduzione del manuale in una determinata lingua
    e si sarà contattati da qualcuno che aiuterà o a cominciare una nuova traduzione
    o a entrare in contatto con il gruppo di documentazione della propria lingua.
   </para>
  </note>
  <para>
   Al momento il manuale è disponibile, anche parzialmente, in più di 10 lingue.
  </para>
  <para>
   Tutte le versioni possono essere scaricate da: <link xlink:href="&url.php.docs;">&url.php.docs;</link>.
  </para>
 </sect1>

</appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->