Trucchi e consigli per lo sviluppo della documentazione

1.Impostare l'ambiente locale

Ambiente locale per i collaboratori 

Creare una directory dedicata allo sviluppo della documentazione. Si prende come esempio ~/work/gentoo/doc. All'interno di questa directory, si crea una sotto-directory (per esempio, en/) nella quale si terrà la documentazione inglese aggiornata.

Si scarica il pacchetto con la documentazione inglese più recente:

# wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-en.tar.bz2

Si decomprime la documentazione nella directory en/. Ora si possiede un'immagine aggiornata della documentazione inglese. Ogni volta che si desidera aggiornare questa immagine, si può scaricare nuovamente il pacchetto, ma è anche possibile caricare la pagina del documento e aggiungere ?passthru=1 all'URL. Per esempio:

# wget http://www.gentoo.org/doc/en/alsa-guide.xml?passthru=1 -O alsa-guide.xml

Nel caso si voglia aiutare nella traduzione dei documenti, si consiglia di creare una directory per la propria lingua, nella quale si terranno le traduzioni correnti:

# mkdir ${LANG}
# cd ${LANG}
# wget http://www.gentoo.org/dyn/doc-snapshots/docs-latest-${LANG}.tar.bz2
# tar xvjf docs-latest-*.tar.bz2

Quando si aggiorna un documento, è necessario copiarlo dalla directory ${LANG}/ a quella principale (~/work/gentoo/doc) e modificare la versione copiata. È necessario avere l'originale per creare una patch:

# diff -uNt ${LANG}/alsa-guide.xml alsa-guide.xml > alsa-guide.diff

Deposito CVS online 

Si può richiedere 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.

Deposito locale per gli sviluppatori 

Si crea una directory dedicata a Gentoo; per esempio ~/work/gentoo/doc. Poi si crea una sotto-directory chiamata cvs/ nella quale si metterà l'immagine del CVS.

# mkdir cvs; cd cvs/
# export CVSROOT=<il proprio nick>@cvs.gentoo.org:/var/cvsroot
# cvs co doc

Per aggiornare l'immagine CVS, eseguire il comando cvs update -dP nella directory cvs/doc.

2.Provare GuideXML

Provare l'ambiente 

Prima si crea una directory test/ nella quale si copiano guide.dtd, main.css e alcune immagini:

# mkdir test
# cd test
# mkdir css images
# wget -P css/ http://www.gentoo.org/css/main.css
# wget -P images/ http://www.gentoo.org/images/gbot-s.gif \
  http://www.gentoo.org/images/gridtest.gif \
  http://www.gentoo.org/images/gtop-s.jpg \
  http://www.gentoo.org/images/line.gif \
  http://www.gentoo.org/images/netraverse-gentoo.gif

Ora si scarica una versione speciale di guide.xsl ottenibile dal sito web di SwifT. Questa versione è modificata per trasformare GuideXML in HTML su sistemi locali.

# wget http://dev.gentoo.org/~swift/local/guide.xsl

Infine, si modifica /etc/xml/catalog aggiungendo le linee seguenti:

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

Provare una guida di Gentoo 

Per provare una guida di Gentoo, per prima cosa si controlla se utilizza una corretta sintassi XML:

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

Se xmllint termina senza indicare nulla, la sintassi XML del file è corretta. Quindi è necessario convertirlo in HTML. xsltproc è il programma utilizzato per fare ciò:

# xsltproc --novalid test/guide.xsl alsa-guide.xml > test/alsa-guide.html

Se non è indicato nessun errore, si dovrebbe essere in grado di aprire il file con il proprio browser (digitando file:///home/user/work/gentoo/doc/test/alsa-guide.html nella barra degli indirizzi, dove user è il nome del proprio utente) per visualizzare il documento. Se non è possibile farlo, correggere la propria guida finchè non funziona.

Provare il Manuale di Gentoo 

Il Manuale di Gentoo è diviso in capitoli. Per trasformare in HTML un determinato capitolo, è necessario usare sia il file handbook-x86.xml sia il file hb- desiderato (per esempio, hb-install-about.xml). Quindi bisogna eseguire xsltproc dando gli stessi parametri utilizzati mentre si sfoglia online il manuale, indicando part e chap. Ad esempio, per verificare la validità di hb-install-about.xml:

# xmllint --valid --noout handbook-x86.xml
# xmllint --valid --noout hb-install-about.xml
# xsltproc --stringparam part 1 --stringparam chap 1 test/guide.xsl \
handbook-x86.xml > test/hb-install-about.html

3.Usare un'installazione di axkit

Alcuni sviluppatori di documenti preferiscono utilizzare un'installazione di axkit simile a quella che è usata su http://www.gentoo.org. Di seguito alcune dritte per installare una configurazione simile.

Per prima cosa si installano i pacchetti richiesti:

(Controllare se i pacchetti sono disponibili in portage)
# emerge -vp =libxml2-2.5.8 =libxslt-1.0.33 =AxKit-1.6.1 =XML-XPath-1.13 \
 =XML-LibXML-1.54-r1 =XML-LibXSLT-1.53 =XML-Parser-2.31-r1 =apache-1.3.29-r1

These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild   R   ] dev-libs/libxml2-2.5.8  -ipv6 +python +readline  0 kB 
[ebuild   R   ] dev-libs/libxslt-1.0.33  +python  0 kB 
[ebuild   R   ] dev-perl/AxKit-1.6.1  +gnome  0 kB 
[ebuild   R   ] dev-perl/XML-XPath-1.13   0 kB 
[ebuild   R   ] dev-perl/XML-LibXML-1.54-r1   0 kB 
[ebuild   R   ] dev-perl/XML-LibXSLT-1.53   0 kB 
[ebuild   R   ] dev-perl/XML-Parser-2.31-r1   0 kB
[ebuild   R   ] net-www/apache-1.3.29-r1  +pam  0 kB

(Installare i pacchetti)
# emerge -v =libxml2-2.5.8 =libxslt-1.0.33 =AxKit-1.6.1 =XML-XPath-1.13 \
 =XML-LibXML-1.54-r1 =XML-LibXSLT-1.53 =XML-Parser-2.31-r1 =apache-1.3.29-r1

Quindi si modificano i seguenti file di configurazione:

(All'interno)
<IfModule mod_dir.c>
  (Aggiungere index.xml alla lista)
  (ndT: se apache dovesse dare un errore riguardo al file commonapache.conf, 
   si consiglia di porre gli argomenti di DirectoryIndex in un'unica riga)
  DirectoryIndex index.xml index.html index.php index.php3 \
  index.shtml index.cgi index.pl index.htm Default.htm default.htm
</IfModule>

(Aggiungere le linee seguenti)
<IfDefine PERL>
  LoadModule perl_module extramodules/libperl.so
#  AddModule mod_perl.c
  PerlModule AxKit
  SetHandler perl-script
  PerlHandler Apache::AxKit::StyleChooser::PathInfo AxKit
  AddHandler axkit .xml .xsp
  AxAddPlugin Apache::AxKit::StyleChooser::QueryString
  AxAddXSPTaglib AxKit::XSP::Util
  AxAddXSPTaglib AxKit::XSP::IfParam
  AxAddXSPTaglib AxKit::XSP::Param
  AxAddStyleMap application/x-xsp Apache::AxKit::Language::XSP
  AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
  <AxStyleName "#default">
    AxAddProcessor text/xsl /xsl/guide.xsl
  </AxStyleName>
  <AxStyleName printable>
    AxAddProcessor text/xsl /xsl/guide-print.xsl
  </AxStyleName>
</IfDefine>

(All'interno)
<IfModule mod_alias.c>
    Alias /icons/ /var/www/localhost/icons/
(Commentare la linea seguente)
    #Alias /doc /usr/share/doc

(Aggiungere -D PERL alla lista delle opzioni)
APACHE_OPTS="-D PERL"

Quindi si copiano i file di documentazione, includendo i file DTD e i fogli di stile, in /var/www/localhost/htdocs/. È necessario avere le directory css/, doc/, dtd/, images/ e xsl/. Gli sviluppatori gentoo possono copiarli o creare un symlink alla loro copia CVS locale. Gli altri collaboratori devono scaricare i file dalla nostra interfaccia viewCVS.

Ciò che resta è far partire il server apache:

# /etc/init.d/apache start
# (Aggiungerlo al runlevel di default se si vuole che venga eseguito automaticamente all'avvio)
# rc-update add apache default

Ora è possibile collegarsi al sito http://tuo_server/doc/en/ o semplicemente http://localhost/doc/en/ se axkit è stato installato sul proprio computer. Si può controllare il file /var/log/apache/access_log per gli accessi e /var/log/apache/error_log per gli errori.

4.Domande frequenti

Come posso convertire un file in UTF-8? 

Ci sono alcuni programmi che posso aiutare. Uno molto conosciuto è app-text/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

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 usati in tutti i manuali, quindi qualunque file di questo tipo deve essere universale 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 o farlo nel modo sbagliato 

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.

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

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