Menu
▾
▴
[Firebird-checkins] CVS: manual/src/docs/firebirddocs-it docbuilding-howto-it.xml, 1.7, 1.8
|
From: Mimmo M. <uma...@us...> - 2009-10-26 15:46:22
|
Update of /cvsroot/firebird/manual/src/docs/firebirddocs-it In directory fdv4jf1.ch3.sourceforge.com:/tmp/cvs-serv30682/src/docs/firebirddocs-it Modified Files: docbuilding-howto-it.xml Log Message: docbuild vs. 1.6.1-it Index: docbuilding-howto-it.xml =================================================================== RCS file: /cvsroot/firebird/manual/src/docs/firebirddocs-it/docbuilding-howto-it.xml,v retrieving revision 1.7 retrieving revision 1.8 diff -b -U3 -r1.7 -r1.8 --- docbuilding-howto-it.xml 9 May 2007 15:33:25 -0000 1.7 +++ docbuilding-howto-it.xml 26 Oct 2009 15:46:00 -0000 1.8 @@ -20,7 +20,7 @@ <contrib>Traduzione in italiano</contrib> </othercredit> - <edition>9 maggio 2007 â Versione italiana 1.5-it</edition> + <edition>26 ottobre 2009 â Versione italiana 1.6.1-it</edition> </articleinfo> <section id="docbuildhowto-intro-it"> @@ -310,14 +310,30 @@ <para>Verranno descritti entrambi i metodi nelle prossime sezioni, iniziando col checkout anonimo. Clicca <link linkend="docbuildhowto-ssh-checkout-it">qui</link> per andare alla - sezione che riguarda il checkout SSH.</para> + sezione che riguarda il checkout SSH (dopo aver letto l'avvertenza + seguente).</para> <warning> - <para>Nel caso in cui si sia all'interno di un firewall, assicurarsi - che la porta 2401 TCP sia aperta. In caso contrario non si è in grado - di effettuare la connessione al server cvs. La propria connessione - semplicemente viene interrotta per tempo scaduto mentre cerca ancora - di collegarsi.</para> + <title>Avvertenze</title> + + <itemizedlist> + <listitem> + <para>Nel caso in cui si sia all'interno di un firewall, + assicurarsi che la porta 2401 TCP sia aperta. In caso contrario + non si è in grado di effettuare la connessione al server cvs. La + propria connessione semplicemente viene interrotta per tempo + scaduto mentre cerca ancora di collegarsi.</para> + </listitem> + + <listitem> + <para>Se possibile, effettuare il checkout in un percorso locale + che non contenga nei nomi delle directory spazi o altri caratteri + speciali soggetti ad essere codificati come nelle URL (es.: lo + spazio diventa '%20'). Altrimenti potrebbero esserci problemi + ricostruendo certi tipi di documenti. Sono problemi comunque + risolvibili, ma è meglio evitarli.</para> + </listitem> + </itemizedlist> </warning> <section id="docbuildhowto-anon-checkout-it"> @@ -783,7 +799,7 @@ necessario.</para> </section> - <section id="docbuildhowto-buidling-output-docs-it"> + <section id="docbuildhowto-building-output-docs-it"> <title>Generare i documenti HTML e PDF</title> <para>Se siete arrivati fin qui, adesso siete pronti per costruire i @@ -832,34 +848,60 @@ <para>Qualsiasi cosa venga fatta starà nell'albero dei direttori sotto <filename>manual/dist</filename></para> + </listitem> + </orderedlist> <note> <title>sulla ricostruzione dei PDF</title> <itemizedlist> <listitem> - <para>Costruendo il file PDF si ricevono moltissimi messaggi - di errore. Si possono tranquillamente ignorare, l'importante è - che nelle ultime linee si legga <literal>BUILD + <para>Costruendo il file PDF si ricevono moltissimi messaggi di + errore. Si possono tranquillamente ignorare, l'importante è che + nelle ultime linee si legga <literal>BUILD SUCCESSFUL</literal>.</para> </listitem> <listitem> <para>A causa di alcune limiti nel software di ricostruzione, - alcuni file PDF possono necessitare di essere rifiniti a mano, - per renderli presentabili. Per uso personale vanno benissimo, - nel senso che <quote>c'è dentro tutto</quote>. Nel caso si - desiderasse migliorarli, si legga la sezione verso la fine di - questa guida riguardo <link - linkend="docbuildhowto-pdfimprove-it"><citetitle>il + alcuni file PDF possono necessitare di essere rifiniti a mano, per + renderli presentabili. Per uso personale vanno benissimo, nel + senso che <quote>c'è dentro tutto</quote>. Nel caso si desiderasse + migliorarli, si legga la sezione verso la fine di questa guida + riguardo <link linkend="docbuildhowto-pdfimprove-it"><citetitle>il perfezionamento dei documenti PDF</citetitle></link>.</para> </listitem> </itemizedlist> </note> - </listitem> - </orderedlist> - <section> + <warning> + <para>Se la copia locale del modulo del manuale è in un percorso che + contiene nel nome degli spazi o altri caratteri speciali non + alfanumerici, la ricostruzione del PDF può non funzionare perché un + file intermedio viene posto in un percorso creato ex-novo con lo + stesso nome, tranne per il fatto che tutti i caratteri + <quote>dannosi</quote> vengono sostituiti con la loro controparte + codificata URL: gli spazi diventano <literal>%20</literal>, + ecc.</para> + + <para>Anche la costruzione del file monohtml (sarebbe come html, ma è + costituito da una sola lunghissima pagina web) va a finire dentro il + percorso codificato come URL. Invece le immagini che dovrebbero + andarci insieme sono salvate nel percorso originale. Tutto questo + ambaradà n è causato da una classe Java che ha alcuni compiti durante + la costruzione ma purtroppo anche converte in URL i nomi dei percorsi + durante il processo.</para> + + <para>Il miglior modo per evitare questi problemi è mettere il modulo + del manuale in un percorso che contenga solo lettere non accentate, + numeri e i caratteri '-' e '_'. La seconda scelta è rendere il + percorso codificato come URL un link simbolico al reale percorso + originale. Dopo aver fatto il link simbolico, tutte le costruzioni + future andranno a meraviglia. Tuttavia questo potrebbe non essere + fattibile in Windows.</para> + </warning> + + <section id="docbuildhowto-building-non-english-it"> <title>Documentazione non inglese con <parameter>-Dsfx</parameter></title> @@ -892,23 +934,21 @@ </warning> </section> - <section> - <title>Manuali parziali con <parameter>-Drootid</parameter></title> + <section id="docbuildhowto-building-subsets-it"> + <title>Manuali parziali con <parameter>-Did</parameter></title> <para>Gli esempi fatti finora producono l'intero insieme (per una - lingua). Per costruire un manuale con solo una parte (esempio un libro - o un articolo particolare) si usa il parametro - <parameter>-Drootid</parameter>. Questo è utile quando si costruiscono - i file PDF, perchè l'intero set diventa un solo grosso file di - dimensioni enormi.</para> + lingua). Di solito però non è questo che si vuole ottenere. Per + generare uno specifico documento (esempio un libro o un articolo + particolare) si usa il parametro <parameter>-Did</parameter>.</para> - <para>Con l'argomento <parameter>-Drootid</parameter> si deve - specificare l'ID dell'elemento da costruire, ad esempio:</para> + <para>Con l'argomento <parameter>-Did</parameter> si deve specificare + l'ID dell'elemento da costruire, ad esempio:</para> <blockquote> - <para><command>build pdf -Drootid=fbutils</command></para> + <para><command>build pdf -Did=fbutils</command></para> - <para><command>build pdf -Dsfx=fr -Drootid=qsg15-fr</command></para> + <para><command>build pdf -Dsfx=fr -Did=qsg15-fr</command></para> </blockquote> <para>Come conoscere l'ID? Si trova nei sorgenti XML DocBook. Si deve @@ -923,40 +963,40 @@ insieme.</para> </section> - <section> + <section id="docbuildhowto-building-other-basesets-it"> <title>Costruire un diverso insieme con - <parameter>-Dbasename</parameter></title> + <parameter>-Dbase</parameter></title> <para>A partire dal gennaio del 2006, le Note di Rilascio (Release Notes) sono state integrate col modulo del manuale, ma costituiscono un insieme da sole, parallelo all'insieme dei documenti <quote><literal>firebirddocs</literal></quote>. Questo ha generato un - altro parametro, <parameter>-Dbasename</parameter>, il cui valore deve + altro parametro, <parameter>-Dbase</parameter>, il cui valore deve essere <quote><literal>rlsnotes</literal></quote> per costruire le Release Notes:</para> <blockquote> - <para><command>build pdf -Dbasename=rlsnotes</command></para> + <para><command>build pdf -Dbase=rlsnotes</command></para> - <para><command>build pdf -Dbasename=rlsnotes - -Drootid=rlsnotes20</command></para> + <para><command>build pdf -Dbase=rlsnotes -Did=rlsnotes210 + -Dsfx=it</command></para> - <para><command>build pdf -Dbasename=rlsnotes - -Dsfx=fr</command></para> + <para><command>build pdf -Dbase=rlsnotes -Dsfx=fr</command></para> </blockquote> - <para>Nel frattempo è stato aggiunto un altro insieme, - <literal>papers</literal>, ancora da tradurre in italiano.</para> + <para>Nel frattempo sono stati aggiunti altri due insiemi, + <literal>papers</literal> e <literal>refdocs</literal>, non ancora + tradotti in italiano.</para> <para>Il risultato di vari insiemi è scritto nei soliti direttori, tranne in un caso: il multi-file documento finale di tipo <systemitem>html</systemitem> è messo in - <filename>manual/dist/html-<basename></filename>, per evitare + <filename>manual/dist/html-<base></filename>, per evitare ambiguità con altri insiemi e pertanto i vari file <filename>index.html</filename> non si sovrascrivono l'un l'altro. Gli insiemi non in inglese vanno in - <filename>manual/dist/html-<basename>/<sfx></filename>. - Per esempio le note di rilascio in inglese sono scritte in + <filename>manual/dist/html-<base>/<sfx></filename>. Per + esempio le note di rilascio in inglese sono scritte in <filename>manual/dist/html-rlsnotes</filename>, quelle in francese invece in <filename>manual/dist/html-rlsnotes/fr</filename>.</para> @@ -966,7 +1006,7 @@ solo nome.</para> </section> - <section> + <section id="docbuildhowto-building-defaults-it"> <title>Impostare valori di default in <filename>build.xml</filename></title> @@ -982,16 +1022,16 @@ <para>Ovviamente, facendo uso di questa caratteristica, si possono ancora costruire le altre cose specificando le proprie intenzioni sulla linea di comando. Per esempio, nel caso in cui si sia impostato - <parameter>basename</parameter> a <literal>rlsnotes</literal> nel file - di impostazione dei default, si può costruire l'insieme completo - standard con:</para> + <parameter>base</parameter> a <literal>rlsnotes</literal> nel file di + impostazione dei default, si può costruire l'insieme completo standard + con:</para> <blockquote> - <para><command>build html -Dbasename=firebirddocs</command></para> + <para><command>build html -Dbase=firebirddocs</command></para> </blockquote> </section> - <section> + <section id="docbuildhowto-building-conclusions-it"> <title>Ricostruire la documentazione â conclusioni</title> <para>Ecco fatto â adesso si è un perfetto ricostruttore patentato di @@ -1051,8 +1091,8 @@ <para>Se non funziona il processo di ricostruzione, la causa potrebbe essere dovuta ad una versione di Java 2 troppo vecchia. Ricontrollate - <xref linkend="docbuildhowto-get-java2-it" /> per maggiori informazioni - per avere la versione più recente.</para> + <citetitle><xref linkend="docbuildhowto-get-java2-it" /></citetitle> per + maggiori informazioni onde ottenere la versione più recente.</para> <para>Altrimenti, se un messaggio di errore dice che una classe o la definizione di una classe non sono state trovate, probabilmente non sono @@ -1060,6 +1100,20 @@ Ricontrollate nel <filename>manual/lib/_readme_libs.txt</filename> e seguite le istruzioni (in inglese).</para> + <para>Se la costruzione di un PDF termina con <literal>BUILD</literal> + <literal>SUCCESSFUL</literal> ma un paio di linee prima dice + <quote><computeroutput>No files processed. No files were + selected...</computeroutput></quote> ed effettivamente non c'è il file + PDF, questo potrebbe essere causato da spazi o da altri caratteri + <quote>dispettosi</quote> nel percorso del file. Vedere le avvertenze in + <link linkend="docbuildhowto-building-output-docs-it"><citetitle>Building + the HTML and PDF docs</citetitle></link>.</para> + + <para>Se si riesce ad avere il PDF ma il documento prodotto risulta poco + presentabile, seguire i consigli esposti nella prossima sezione: <link + linkend="docbuildhowto-pdfimprove-it"><citetitle>Improving the + PDF</citetitle></link>. Possono trovarvisi varie soluzioni.</para> + <para>Se qualcos'altro non va e non si capisce cosa, chiedete aiuto alla mailing list firebird-docs. E' necessario dare una buona descrizione del problema per ottenere un buon aiuto. Se non siete ancora iscritti alla @@ -1136,14 +1190,14 @@ esempio,</para> <blockquote> - <para><command>build fo -Drootid=qsg15</command></para> + <para><command>build fo -Did=qsg15</command></para> </blockquote> <para>...trasforma il sorgente della Quick Start Guide 1.5 in <filename>manual/inter/qsq15.fo</filename>. E</para> <blockquote> - <para><command>build fo2pdf -Drootid=qsg15</command></para> + <para><command>build fo2pdf -Did=qsg15</command></para> </blockquote> <para>...produce il PDF dal file FO (che deve ovviamente essere presente @@ -1270,6 +1324,29 @@ <section id="docbuildhowto-pdfimprove-solutions-it"> <title>Problemi tipici e loro soluzioni</title> + <itemizedlist spacing="compact"> + <listitem> + <para><link linkend="docbuildhowto-pdfimprove-widows-it">Testate + vedove</link></para> + </listitem> + + <listitem> + <para><link linkend="docbuildhowto-pdfimprove-splitrows-it">Righe di + tabella o di elementi in lista interrotti</link></para> + </listitem> + + <listitem> + <para><link linkend="docbuildhowto-pdfimprove-widespaces-it">Spazi + orrizontali enormemente larghi</link></para> + </listitem> + + <listitem> + <para><link + linkend="docbuildhowto-pdfimprove-massacredformals">Contenuti di + pagina compressi, troncati o scombussolati</link></para> + </listitem> + </itemizedlist> + <section id="docbuildhowto-pdfimprove-widows-it"> <title>Testate vedove</title> @@ -1359,9 +1436,8 @@ Il titolo della sezione adesso apparirà alla successiva pagina nuova, e si può passare al problema successivo.</para> - <section> - <title id="docbuildhowto-pdfimprove-widows-noid-it">Quando manca il - DocBook ID</title> + <section id="docbuildhowto-pdfimprove-widows-noid-it"> + <title>Quando manca il DocBook ID</title> <para>E se l'elemento di DocBook non ha un suo id? Allora si dovrà cercare il (o parte del) titolo o della testata. Questo sarà un po' @@ -1433,9 +1509,8 @@ </section> </section> - <section> - <title id="docbuildhowto-pdfimprove-splitrows-it">Righe di tabella o - di elementi in lista interrotti</title> + <section id="docbuildhowto-pdfimprove-splitrows-it"> + <title>Righe di tabella o di elementi in lista interrotti</title> <para><emphasis>Problema:</emphasis> In una tabella, una riga è interrotta da un salto pagina per cui non è tutta da una parte o @@ -1467,9 +1542,8 @@ class="attribute">break-after</sgmltag> alla riga precedente.</para> </section> - <section id="docbuildhowto-pdfimprove-splitrows-it"> - <title id="docbuildhowto-pdfimprove-widespaces-it">Spazi orrizontali - enormemente larghi</title> + <section id="docbuildhowto-pdfimprove-widespaces-it"> + <title>Spazi orrizontali enormemente larghi</title> <para><emphasis>Problema:</emphasis> Spazi molto larghi per giustificare linee precedenti lunghe stringhe senza spazi. Queste @@ -1521,25 +1595,25 @@ punto. Non resta che cancellare lo spazio che si è aggiunto e interrompere la stringa nel punto deciso da Apache.</para> - <section> - <title id="docbuildhowto-pdfimprove-widespaces-zwsp-it">Inserire - spazi di dimensione zero</title> + <section id="docbuildhowto-pdfimprove-widespaces-zwsp-it"> + <title>Inserire spazi di dimensione zero</title> <para>Una soluzione alternativa al problema degli spazi enormi sarebbe inserire spazi di dimensione zero proprio in tutti i punti in cui la stringa in esame potrebbe essere mandata a capo, lasciando decidere Apache FOP quale è il più adatto. Questo funziona - sicuramente al primo tentativo, ma:</para> + sicuramente al primo tentativo, ma si può fare solo a queste + condizioni:</para> <itemizedlist> <listitem> - <para>si può fare solo avendo un editor che permette di inserire - facilmente gli ZWSP;</para> + <para>avendo un editor che permette di inserire facilmente gli + ZWSP;</para> </listitem> <listitem> - <para>funziona solo dove è possibile interrompere la stringa - senza il <quote>-</quote>;</para> + <para>dove è possibile interrompere la stringa senza il + <quote>-</quote>;</para> </listitem> </itemizedlist> </section> @@ -1946,12 +2020,11 @@ secondo elemento in lista.</para> <para><citetitle>Manuali parziali con - <parameter>-Drootid</parameter></citetitle> â Cambiato il - paragrafo che comincia con <quote>Come conoscere - l'ID?</quote></para> + <parameter>-Did</parameter></citetitle> â Cambiato il paragrafo + che comincia con <quote>Come conoscere l'ID?</quote></para> <para><citetitle>Costruire un diverso insieme con - <parameter>-Dbasename</parameter></citetitle> â Aggiunto il + <parameter>-Dbase</parameter></citetitle> â Aggiunto il riferimento all'insieme dei <literal>papers</literal>.</para> <para><citetitle>Argomento avanzato: perfezionare i @@ -2007,6 +2080,127 @@ documenti per Firebird</citetitle>.</para> </revdescription> </revision> + + <revision> + <revnumber>1.6</revnumber> + + <date>24 Oct 2009</date> + + <authorinitials>PV</authorinitials> + + <revdescription> + <para><citetitle>Fare il "check out" del modulo del + manuale</citetitle> â Aggiunto un avviso per non mettere la copia + locale in un percorso contenente spazi o altri caratteri + suscettibili di <quote>conversione</quote> nelle URL. Messi gli + avvisi in una lista, mettendo un titolo esplicito, e modificato il + paragrafo precedente.</para> + + <para><citetitle>Generare i documenti HTML e PDF</citetitle> â + Aggiunto l'avviso a non utilizzare percorsi contenenti caratteri + che possono cambiare a causa della codifica URL, e spiegato come + aggirare il problema. Messi gli id alle cinque + sottosezioni.</para> + + <para><citetitle>Manuali parziali con + <parameter>-Did</parameter></citetitle>, <citetitle>Costruire un + diverso insieme con <parameter>-Dbase</parameter></citetitle>, + <citetitle>Impostare valori di default in + <filename>build.xml</filename></citetitle> e <citetitle>Come viene + ricostruito il PDF</citetitle> â Sostituito + <literal>-Drootid</literal> con <literal>-Did</literal> e + <literal>-Dbasename</literal> con <literal>-Dbase</literal> in + tutte queste sezioni.</para> + + <para><citetitle>Manuali parziali con + <parameter>-Did</parameter></citetitle> â Modificato il primo + paragrafo.</para> + + <para><citetitle>Costruire un diverso insieme con + <parameter>-Dbase</parameter></citetitle> â Modificato il + paragrafo che inizia con <quote>Nel frattempo...</quote>.</para> + + <para><citetitle>Se qualcosa non va</citetitle> â Aggiunto un + paragrafo sul problemi dei caratteri non sicuri nel percorso dei + file perchè vengono codificati come URL.</para> + + <para><citetitle>Quando manca il DocBook ID</citetitle> â Dato un + id a questa sottosezione.</para> + + <para><citetitle>Inserire spazi di dimensione zero</citetitle> â + Cambiata la frase del secondo elemento in lista.</para> + + <para><citetitle>Licenza d'uso</citetitle> â (C) 2003â2007 -> + 2003â2009.</para> + </revdescription> + </revision> + + <revision> + <revnumber>1.6.1</revnumber> + + <date>26 Oct 2009</date> + + <authorinitials>PV</authorinitials> + + <revdescription> + <para><citetitle>Generare i documenti HTML e PDF</citetitle> â + Aggiustati gli ID di questa sezione e di cinque delle sue + sottosezioni, che contenevano la parola + <quote><literal>buidling</literal></quote> invece di + <quote><literal>building</literal></quote>:<itemizedlist + spacing="compact"> + <listitem> + <para><literal>docbuildhowto-buidling-output-docs</literal></para> + </listitem> + + <listitem> + <para><literal>docbuildhowto-buidling-non-english</literal></para> + </listitem> + + <listitem> + <para><literal>docbuildhowto-buidling-subsets</literal></para> + </listitem> + + <listitem> + <para><literal>docbuildhowto-buidling-other-basesets</literal></para> + </listitem> + + <listitem> + <para><literal>docbuildhowto-buidling-defaults</literal></para> + </listitem> + + <listitem> + <para><literal>docbuildhowto-buidling-conclusion</literal></para> + </listitem> + </itemizedlist></para> + + <para><citetitle>Se qualcosa non va</citetitle> â Aggiustato il + link a <citetitle>Generare i documenti HTML e PDF</citetitle>: + <literal>buidling</literal> -> <literal>building</literal>. + Nella stessa frase, le parole <quote>alla fine di</quote> sono + state cambiate con <quote>in</quote>, perchè la destinazione del + link non è alla fine della sezione (è subito prima della prima + sottosezione).</para> + + <para><citetitle>Quando manca il DocBook ID</citetitle> â Rimosso + i'attributo ID dall'elemento del titolo, perchè non è necessario e + perchè era un duplicato dell'ID della sezione e pertanto non + valido.</para> + </revdescription> + </revision> + + <revision> + <revnumber>1.6.1-it</revnumber> + + <date>26 ott 2009</date> + + <authorinitials>UM</authorinitials> + + <revdescription> + <para>Quarta revisione italiana, con le modifiche fino alla rev. + 1.6.1 di PV.</para> + </revdescription> + </revision> </revhistory></para> </appendix> @@ -2027,7 +2221,7 @@ <para>L'autore iniziale del documento originale è: Paul Vinkenoog.</para> - <para>Copyright © 2003â2007. Tutti i diritti riservati. Per contattare + <para>Copyright © 2003â2009. Tutti i diritti riservati. Per contattare l'autore: paul at vinkenoog dot nl.</para> <para>Contributi: Norman Dunbar â vedi le <link |