Trucchi e consigli per lo sviluppo della documentazione

1.  Recuperare i file per le pagine web

Utilizzare il CVS anonimo

I contributori dovrebbero utilizzare il nostro server CVS anonimo. Questo server contiene gli stessi file del CVS ufficiale che utilizzano gli sviluppatori. Il repository CVS anonimo è aggiornato ogni ora.

Si crei una directory dedicata al solo sviluppo della documentazione, e poi si recuperino i file per le pagine web.

$ cvs -d :pserver:anonymous@anoncvs.gentoo.org/var/cvsroot co gentoo/xml

Per aggiornare la propria copia locale del repository, si esegua cvs update -dP all'interno della directory gentoo/xml.

Repository live per gli sviluppatori Gentoo

Se non è stato ancora fatto il checkout del modulo gentoo, lo si faccia ora:

$ export CVSROOT=<your nick>@cvs.gentoo.org:/var/cvsroot
$ cvs co gentoo/xml

Per aggiornare la propria copia del repository, si esegua cvs update -dP all'interno della directory gentoo/xml.

Deposito CVS online

Si può interrogare il deposito CVS online per ottenere le differenze tra singole versioni. Si può accedere al deposito inglese principale da questo link (ndT: quello italiano è reperibile a questo link). Il deposito CVS online è aggiornato ogni ora.

2.  Preparare il proprio ambiente locale

Installare gorg

La nostra documentazione GuideXML è trasformata in HTML dal tool www-servers/gorg. E' quindi necessario provvedere alla sua installazione.

Si seguano le indicazioni sulla pagina web di gorg per la sua configurazione. E' necessario specificare la root per le pagine web dove è stato fatto il checkout dal nostro repository CVS ([..]/gentoo/xml/htdocs). Gli altri parametri sono utili solo se si vuole offrire una copia locale di www.gentoo.org.

Configurare il proprio ambiente XML

Il proprio sistema deve sapere dove trovare i DTD utilizzati dalla nostra documentazione. Si editi /etc/xml/catalog come root e si aggiunga la linea seguente:

<rewriteURI uriStartString="/dtd" rewritePrefix="/usr/portage/metadata/dtd/"/>

Se il proprio /etc/xml/catalog è vuoto o non contiene nessun elemento, è necessario inserire l'elemento <rewriteURI> all'interno dell'elemento <catalog>:

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI uriStartString="/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>
</catalog>

Inoltre, alcuni file potrebbero specificare il DTD on-line con un'uri come http://www.gentoo.org/dtd/guide.dtd. E' possibile rinominare questi riferimenti ed evitare così accessi lenti alla rete durante la fase di validazione:

<rewriteURI uriStartString="http://www.gentoo.org/dtd/" rewritePrefix="/usr/portage/metadata/dtd/"/>

Controllare una guida di Gentoo

Per controllare una guida di Gentoo, per prima cosa si utilizzi xmllint (presente in dev-libs/libxml2) per controllare se utilizza una sintassi XML valida:

$ xmllint --valid --noout alsa-guide.xml

Se xmllint termina senza indicare nulla, allora la struttura del file è valida. Successivamente è necessario convertirla in HTML:

$ gorg < alsa-guide.xml > alsa-guide.html

Se non è indicato nessun errore, si dovrebbe essere in grado di aprire col proprio browser alsa-guide.html per osservare il documento risultante. Se non compare, si corregga il proprio documento finchè funziona.

Navigare la propria copia locale del sito web di Gentoo

Poiché è stato fatto il checkout di una copia del sito di Gentoo dal nostro CVS, è anche possibile utilizzare gorg per navigare nella vostra copia locale. Ci si assicuri di aver scaricato l'indice delle news come spiegato sulla pagina web di gorg se si vuole vedere esattamente la stessa pagina principale.

3.  Domande frequenti

Come posso convertire un file in UTF-8?

Ci sono alcuni programmi che posso aiutare. Uno molto conosciuto è app-test/recode. Un altro è iconv, contenuto nel pacchetto sys-libs/glibc.

Recode è molto semplice da usare. Si indica la codifica dei caratteri usata dal file e quella che invece si vuole utilizzare nel documento convertito.

Per esempio per convertire un documento dalla codifica ISO-8859-15 (conosciuta anche come Latin-9) alla codifica UTF-8, si procede nel modo seguente:

(l9 = ISO-8859-15, u8 = UTF-8)
$ recode l9..u8 file.xml

4.  Suggerimenti sulla Sottomissione di Documentazione

Controllare la correttezza dei tag <guide>

Ci si assicuri che l'attributo <guide link> punti alla corretta locazione per la guida. Questa è generalmente /doc/${LANG}/filename.xml. Se si ha un documento tradotto, si specifichi sempre il percorso assoluto del documento (ad esempio /doc/${LANG}/). Se si sta scrivendo una guida che utilizza i DTD guide o book, è possibile utilizzare sia /doc/${LANG}/filename.xml che filename.xml. In generale, il GDP raccomanda la prima delle due modalità.

Controllare i link

E' necessario controllare che tutti i link ipertestuali nel proprio documento siano corretti. Se si tratta di un documento tradotto, ci si assicuri che i link ad altri documenti tradotti puntino a file esistenti.

Controllate le tabulazioni

Le tabulazioni sono assolutamente proibite nei documenti GuideXML tranne quando necessarie (ad esempio se il documento istruisce gli utenti a come utilizzare le tabulazioni). Per controllare le tabulazioni in un documento, eseguire grep "CTRL+V<TAB>" file.xml. Si sistemino tutte le linee stampate da grep

Bugzilla

Una volta ultimato il documento, lo si sottometta al Documentation Team utilizzando Bugzilla. Non è necessario riportare informazioni come la piattaforma, l'output di emerge info, arch, passi necessari per riprodurre il problema, ecc. Se si possiede un documento tradotto, ci si assicuri di scegliere il campo Doc Translations per il vostro bug. Inoltre, si includa un utile sommario per la vostra traduzione utilizzando il formato favorito: "[fr] New translation: /doc/fr/gnupg-user.xml". Si sostituisca [fr] con il codice a due lettere del vostro linguaggio.

Di default, docs-team@gentoo.org è il destinatario (assignee) del vostro bug: non c'è alcun bisogno di modificare il campo assignee.

Si alleghino file e patch al bug utilizzando la modalità "plain text (text/plain)", anche se si sta sottomettendo un file .xml Le patch dovrebbero avere l'opzione "Patch" marcata. Non si sottomettano tarballs piene di documenti; si alleghi ogni documento e patch individualmente.

5.  Errori comuni o pericolosi

Dimenticare che il Manuale Gentoo riguarda tutte le architetture

I file presenti in [gentoo]/xml/htdocs/doc/it/handbook che non terminano con il suffisso "-<arch>.xml" sono letti da tutti gli handbook, il che significa che tutto ciò che è menzionato al loro interno deve essere vero per ogni architettura.

Se si ha bisogno di apportare delle modifiche per la propria architettura e si teme di dover creare un nuovo file per questo, prima di compiere qualunque modifica bisogna chiedere aiuto a gentoo-doc@gentoo.org. Molte volte c'è una soluzione più semplice che evita di creare problemi agli utenti di altre architetture.

Non modificare la versione e la data

Come esige il regolamento per lo sviluppo della documentazione, si deve cambiare la versione e la data quando si compiono delle modifiche. Sebbene la versione sia meno importante, la data serve agli utenti per sapere quando è avvenuta l'ultima modifica.

Se si sta apportando un cambiamento di contenuto al documento (come istruzioni, esempi di codice, ecc), si deve incrementare la versione. Per cambiamenti non di contenuto (ad esempio errori di scrittura o correzioni nell GuideXML), il salto di versione non è di solito necessario.

Quando si aggiorna il manuale, si deve modificare la data e la versione dei soli file modificati. Non modificare il file handbook-ARCH.xml a meno che non si abbia modificato effettivamente quel file.

Un altro errore comune è aggiornare il numero della versione come se fosse un numero decimale. 3.9 diventa 3.10, non 4.0 o 3.91.

I contenuti di questo documento sono rilasciati sotto la licenza Creative Commons - Attribution / Share Alike.