Gentoo Logo

Trucchi e consigli per lo sviluppo della documentazione

Indice:

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.

Codice 1.1: Recuperare 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:

Codice 1.2: Recuperare il modulo gentoo

$ 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 pacchetto www-servers/gorg. È quindi necessario provvedere alla sua installazione.

Nota: E' necessario utilizzare almeno gorg-0.6.3. Potrebbe essere necessario aggiungerlo in /etc/portage/package.keywords per la vostra architettura.

Seguire le indicazioni per la sua configurazione. È 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:

Codice 2.1: Aggiunta di /etc/xml/catalog

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

Nota: E' possibile anche eseguire il rewrite verso il percorso dove è stato fatto il checkout dei DTD dal CVS.

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

Codice 2.2: /etc/xml/catalog minimale

<?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:

Codice 2.3: Extra /etc/xml/catalog addendum

<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:

Codice 2.4: Usare xmllint per validare GuideXML

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

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

Codice 2.5: Convertire 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.

Nota: Nei capitoli dell'handbook, i link verso gli altri capitolo non saranno generati poiché le versioni on-line accedono ai capitoli dell'handbook tramite il file master e i parametri chap e part.

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. Assicurarsi di aver scaricato l'indice delle news come spiegato nella guida 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:

Codice 3.1: Convertire un file

(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 usando numeri decimali. Non andrebbe fatto, in quanto la versione è un semplice numero intero, e ciascun aggiornamento dovrebbe incrementarlo di una unità. 9 dovrebbe diventare 10, non 9.1. Per i vecchi documenti che ancora non usano il più semplice versionamento con numeri interi, si prega di incrementarlo all'intero più vicino la prossima volta che si effettua un commit. Pertanto 4.67 dovrebbe diventare 5, 1.2 dovrebbe diventare 2, e così via.

Importante: L'eccezione a questa regola è per /doc/en/metadoc.xml. Metadoc deve ancora usare l'esistente schema con il punto decimale. Pertanto 1.119 diventa 1.120, non 2.



Stampa

Aggiornato il 6 dicembre 2010

Oggetto: Alcuni trucchi e consigli che possono rendere più semplice la vita di un redattore di documentazione per Gentoo.

Xavier Neys
Autore

Sven Vermeulen
Autore

Joshua Saddler
Redazione

Matteo Visconti
Traduttore

Gianni Costanzi
Traduttore

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.