Come lavorare sulle pagine web Debian

Informazioni generali

Risorse richieste

Se si vuole lavorare al nostro sito web, bisogna essere preparati a memorizzare almeno 250 MB di dati sul proprio disco. Questa è di fatti l'attuale dimensione dell'archivio dei sorgenti. Se (per errore) si ricostruiscono tutte le pagine, si avrà bisogno almeno del doppio di questo spazio. Se si fa un checkout parziale allora basterà molto meno spazio, come i 50 Mb per la directory english/.

Checkout parziali

Molte persone non vogliono avere tutto l'albero webwml estratto dal CVS ma ciò può causare la mancanza di file e compilazioni errate nel caso qualcuno abbia aggiunto nuovi, cruciali file e non si sia fatto un cvs update completo per quella directory. Si ricordi di verificare la presenza di tutti i file richiesti (come .wmlrc) prima di protestare con noi.

Cosa sono queste linee che cominciano per '#'?

Nel WML una linea che comincia per '#' è un commento. Questa forma è preferita ai commenti HTML perché non è inserita nella pagina finale.

Si legga la pagine su come usare il WML per ulteriori informazioni sul WML.

Etichetta per i redattori

Posso modificare questa pagina?

Dipende. Se ci si accorge di una svista, come un errore di battitura, lo si corregga pure.

Anche se si nota che manca qualche pezzo di informazione si faccia la correzione.

Se si pensa che una parte sia brutta e andrebbe riscritta, si scriva a debian-www in modo che se ne possa parlare. Probabilmente saremo tutti d'accordo.

Se si nota un problema in un template (ad esempio un file nella directory webwml/english/template/debian), si pensi bene prima di fare il commit della modifica, poichè le modifiche ai template fanno spesso in modo che grandi porzioni del sito vengano ricostruite.

Quando si aggiungono nuove directory, si aggiunga anche il Makefile!

Una attenzione particolare va fatta all'aggiunta di directory al CVS. Se la directory attuale è inserita nel ../Makefile allora si deve creare un Makefile nella nuova directory altrimenti make darà un messaggio di errore.

Usare un inglese chiaro e semplice

Poiché le pagine web Debian sono lette da persone che non sono di madre-lingua inglese e che devono tradurre in altre lingue, è meglio scrivere in inglese semplice e chiaro evitando l'uso di forme gergali, dialettali o arcaiche.

Se si utilizza una di queste forme allora si aggiunga un commento che ne spieghi il significato.

Leggere i README

Alcune directory contengono un README che aiuta a capire com'è organizzata la directory. Esso fornisce anche ogni informazione necessaria per lavorare in quell'area.

Separare le modifiche dei contenuti da quelle della formattazione

Effettuare sempre separatamente le patch o i commit con modifiche ai contenuti da quelli con modifiche della formattazione. Se fatti insieme, è molto più difficile per i traduttori trovare le differenze. Se si lancia cvs diff con qualche cambiamento misto, si potrà constatare quale miscuglio ne venga fuori.

In generale evitare modifiche random della formattazione. Rendere vecchie parti delle pagine XHTML/XML-compliant non dovrebbe essere fatto insieme ad altre modifiche nello stesso commit. (E si ricordi che il nuovo materiale può e deve essere scritto bene dall'inizio.)

Aggiornare anche le traduzioni, se possibile

Alcune modifiche sono indipendenti dalla lingua usata nel file WML, come modifiche di URL o di codice Perl. Anche la correzione di errori di battitura rientra nella stessa categoria, poiché i traduttori li avranno ignorati nella traduzione. Perciò con le modifiche indipendenti dalla lingua, si possono effettuare le modifiche in tutti i file tradotti anche non conoscendo le altre lingue ed incrementare il numero di versione negli header translation-check.

Non è difficile per i traduttori fare questo lavoro essi stessi e può esserci l'inconveniente per i redattori di madre lingua inglese di dover avere un checkout completo sul quale operare. Comunque vi incoraggiamo a farlo per evitare che due dozzine di persone lavorino a qualcosa che può essere fatto velocemente da una sola.

In più per rendere l'applicazione di queste modifiche maggiormente facile, si può usare lo script smart_change.pl nella top-level directory del modulo CVS webwml.

Uso di smart_change.pl

smart_change.pl [opzioni] origfile

Al momento solo i file in /english/ sono consentiti come origfile. smart_change.pl accetta i seguenti argomenti:

-s, --substitute=REGEXP
Specifica un'espressione regolare Perl da applicare al file sorgente (se ne possono usare più di una). Esempio: 
	  Esempio: ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/index.wml
          $> ./smart_change.pl -s "s,http://oldurl/,http://newurl/,g" english/devel/index.wml
          $> cvs diff -u */devel/index.wml | less
          $> cvs ci -m "1.23: Updated oldurl to current location" */devel/index.wml
Il primo comando effettua le modifiche, il secondo serve per controllare il file inglese originale ed ogni traduzione di esso. Va usato per controllare le modifiche prima del commit. Se tutto appare in ordine si effettui il commit dei file modificati con il terzo comando.
-l, --lang=STRING
Processa la lingua indicata (se ne possono indicare più di una). Se nessuna lingua è specificata, tutte quelle disponibili sono processate.
-n, --no-bump
Non viene incrementato il numero di versione negli header translation-check. Normalmente la versione di ogni header translation-check è incrementata di uno se le traduzioni sono aggiornate, viene lasciata inalterata se non lo sono. Se questa opzione è specificata nessun header translation-check è modificato. Si veda Mantenere le traduzioni del sito web aggiornate per una spiegazione degli header translation-check.
-p, --previous
Mostra la precedente revisione CVS. Ciò è utile principalmente quando è già stato fatto il commit del file inglese e si vuole controllare l'header translation-check con la versione precedente.
-h, --help
Mostra una breve guida.
-v, --verbose
Mostra messaggi verbosi durante l'esecuzione.

Link

Questo link non mi pare corretto. Posso cambiarlo?

La configurazione del server web comprende l'uso della negoziazione dei contenuti, quindi non si dovrebbe cambiare alcun link interno. In effetti noi suggeriamo di non cambiare alcun link. Se si crede che ce ne siano di non corretti si scriva a debian-www prima di cambiarlo.

Correggere link

Se si nota un link ad un sito web esterno che porta ad una ridirezione (301, 302, a <meta> redirect, o una pagina This page has moved.) si avverta debian-www.

Se si trova un link che non funziona (404, 403 o una pagina che non è quella che dovrebbe esserci), si sistemi il problema e si mandi un messaggio a debian-www in modo che i traduttori possano fare lo stesso aggiornamento. Meglio ancora: si aggiornino tutte le traduzioni e l'intestazione translation-check. :-)

Separazione dei testi dai dati

Cosa sono i file pippo.def e pippo.data?

Per permettere una più semplice traduzione, abbiamo separato le parti generiche (data) dalle parti testuali (text) di alcune pagine. I traduttori devono solo copiare e tradurre le parti testuali di esse, le parti generiche saranno aggiunte automaticamente.

Un esempio può capire ad aiutarne la comprensione. Vengono utilizzati alcuni file per generare la pagina dei listini dei venditori in CD/vendors:

index.wml:
Il testo in cima alla pagina dei venditori si trova in questa pagina. Una copia tradotta di questa pagina dovrebbe trovarsi in ogni directory propria della lingua.
vendors.CD.def:
Questo contiene tutte le parti del testo di cui si ha bisogno per ogni voce dei venditori. Le traduzioni sono aggiunte mediante <lingua>/po/vendors.xy.po.
vendors.CD:
Questo file contiene le voci dei venditori che sono indipendenti dalla lingua, di conseguenza un traduttore non ha bisogno di toccare questo file.

Quando qualcuno tramite cdvendors@debian.org segnala un nuovo venditore, esso sarà aggiunto a debiancd.db, che sarà trasformato in formato WML come vendors.CD (usando getvendors.pl), ed infine WML e i makefile faranno la loro magia: tutte le traduzioni saranno ricostruite usando il testo tradotto già esistente ma con l'aggiunta dei dati del nuovo venditore. (Una traduzione aggiornata in cambio di niente! :-)

Aggiungere nuove pagine

Aggiungere nuove pagine a Debian è molto semplice. Tutto il lavoro di creazione dell'intestazione e del pie' di pagina è fatto da wml. Tutto quello che si deve fare è includere una linea come la seguente all'inizio del nuovo file:

#use wml::debian::template title="Titolo della pagina"

seguita dal corpo del testo. Tutte le pagine dovrebbero usare il modello wml::debian::template a meno che non ne usino uno particolare creato per quella particolare sezione (come le news e le pagine sulla sicurezza.)

Il modello che abbiamo permette di definire alcune variabili che influenzano la pagina creata. Questo dovrebbe evitare di rendere necessario creare altri modelli: molti cambiamenti dovrebbero essere fatti semplicemente. Le variabili attualmente disponibili sono:

BARETITLE="true"
Elimina la parte "Debian GNU/Linux --" che è in genere inserita prima dei tag <title>.
NOHEADER="true"
Rimuove l'intestazione iniziale dalla pagina. Una intestazione personalizzata può essere inclusa nel corpo.
NOMIRRORS="true"
Rimuove la lista dei mirror dalla pagina. Di norma non è consigliato usarlo, fatta eccezione per poche pagine.
NOHOMELINK="true"
Rimuove il link che fa tornare alla pagina principale di Debian, che è normalmente aggiunto nella parte bassa della pagina.
NOLANGUAGES="true"
Rimuove i collegamenti alle altre lingue, che sono di solito aggiunti alla fine della pagina.
GEN_TIME="true"
Mostra come data di ultima modifica quella del file html generato anziché quella del file sorgente wml.
NOCOPYRIGHT="true"
Rimuove il copyright dal pié di pagina.

Si noti che è possibile usare qualsiasi stringa per assegnare un valore a queste variabili: true, yes, foo, non ha importanza.

Un esempio si ha nelle pagine dei port che hanno la loro intestazione. ports/arm/index.wml usa:

#use wml::debian::template title="ARM Port" NOHEADER="yes"

Se si vuole fare qualcosa che non è prevista dal modello attuale, si provi a considerare l'ipotesi di estendere il modello. Se non è possibile estenderlo mantenendo la compatibilità con l'attuale allora si provi a farne uno nuovo che sia un superset di uno esistente. Questo permetterà di convertire la pagine al proprio modello al prossimo grosso aggiornamento (In genere ogni 6 mesi massimo.)

Se si sta creando una pagina che è generata da uno script si provi a vedere se l'uso dei tag di <gettext> può facilitare l'aggiornamento delle traduzioni.

Inclusione di altri file

Se si vuole separare alcune parti della propria pagina in un file distinto (che sarà poi incluso tramite il file principale) si usi l'estensione .src se il file ha dei contenuti che dovrebbero essere tradotti poiché in questo modo le modifiche al file incluso vengono contrallate come per i file .wml ordinari. Se si usa qualsiasi altra estensione, come .inc, i traduttori non saranno avvisati degli aggiornamenti e diversi linguaggi potrebbero avere diversi contenuti.

Aggiungere nuove directory

Nota: Non creare alcuna directory che si chiami install. Questo confonderebbe il programma make e le pagine in quella directory non sarebbero aggiornate automaticamente.

Segue un esempio di come si aggiunge una directory al sito web. 

   mkdir foo
   cvs add foo
   cd foo
   cp ../intro/Makefile .
   cvs add Makefile

Editare il Makefile nella directory padre e si aggiunga la directory attuale nella variabile SUBS. Questo farà sì che la directory sia considerata durante la creazione del sito.

Alla fine si faccia il commit al repository di tutti i cambiamenti 

   cvs commit Makefile foo