Come lavorare sulle pagine web Debian

Informazioni generali

Risorse richieste

Se si vuole lavorare al nostro sito web, bisogna essere preparati a memorizzare almeno 740 MB di dati sul proprio disco. Questa è infatti l'attuale dimensione dell'archivio dei sorgenti. Se (per errore) si ricostruiscono tutte le pagine, si avrà bisogno almeno del triplo di questo spazio.

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 pagina 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!

Un'attenzione particolare va prestata all'aggiunta di directory al repository git. 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 emoticon.

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

In caso di dubbi o correzioni si invita a contattare il team di localizzazione inglese.

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 git diff -u 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.

Inoltre, per rendere l'applicazione di queste modifiche ancora più facile, si può usare lo script smart_change.pl nella directory di livello più alto del modulo git webwml.

Collegamenti

Questo collegamento non è 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ò 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 [email protected] 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 piè 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 --" 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 è previsto 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 le 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 controllate 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
   git add foo
   cd foo
   cp ../intro/Makefile .
   git 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 con 

   git commit Makefile foo