Appendice C. Come contribuire alla guida a NetBSD

Sommario
C.1. Tradurre la guida
C.2. Inviare materiale per la guida
C.3. Schema di disposizione SGML/DocBook

Ultimamente si può notare un notevole aumento dell'interesse verso la documentazione, introduttiva e avanzata, di NetBSD: si tratta indubbiamente di un segno della crescente popolarità del sistema e dell'aumento della base di utenti. Pertanto, è più che mai importante continuare a aggiornare e a accrescere il materiale sia di questa guida sia dei vari HOWTO presenti sul sito di NetBSD.

Indipendentemente dal proprio livello di conoscenza e di esperienza con NetBSD, chiunque può contribuire allo sviluppo di questa guida. Questa appendice spiega in che modo si può contribuire alla guida e cosa bisogna sapere prima di incominciare.

I principianti e, più in generale, coloro che installano il sistema per la prima volta, possono inviare i propri commenti e suggerimenti direttamente a me indicando, per esempio, se qualcosa non ha funzionato, se un argomento non è spiegato in modo sufficientemente chiaro, ecc. Oppure si può anche inviare una richiesta perché sia trattato un determinato argomento. Questo tipo di riscontro è molto utile.

Gli utenti più avanzati possono scrivere una nuova sezione o anche un intero capitolo da aggiungere alla guida. Oppure possono modificare una parte già esistente, aggiungendo esempi, figure o riformulandola in maniera più chiara.

Chi ha un po' di tempo libero può prendere in considerazione l'idea di tradurre la guida in una nuova lingua.

Qualunque cosa scegliate di fare, per prima cosa contattatemi, onde evitare lavoro duplicato o inutile.

C.1. Tradurre la guida

Chi vuole tradurre la guida deve per prima cosa mettersi in contatto con me oppure scrivere alla mailing list netbsd-docs@netbsd.org.

Se altre persone stanno già lavorando a una traduzione della guida nella stessa lingua è possibile aggiungersi al gruppo, abbreviando i tempi di completamento del lavoro. Se nessun altro è al lavoro, è sempre possibile che alcuni capitoli siano già stati tradotti in passato, altrimenti bisogna iniziare una traduzione ex-novo. Qualunque situazione si presenti, non è necessario tradurre l'intera guida: anche la traduzione di un solo capitolo è un contributo utile e apprezzato.

Anche quando una traduzione è già stata completata, è sempre necessario mantenere aggiornata la guida con il nuovo materiale e con le correzioni a quello esistente, ed è quindi possibile diventare il mantainer di una versione della guida.

C.1.2. Come scrivere in formato SGML/DocBook

Per tradurre la guida non è necessario imparare a scrivere in SGML/DocBook: è sufficiente lavorare con un editor sui sorgenti sostituendo il testo originale e lasciando invariati i tag, cioè riutilizzando la struttura del documento. A titolo di esempio, per tradurre la precedente nota si potrebbe operare in questo modo:

Quando si scrive la traduzione è preferibile utilizzare la stessa indentazione e la stessa formattazione della versione originale. Vedere la Sezione C.3 per un esempio.

Un problema che si deve quasi sempre affrontare quando si scrive in SGML/DocBook è quello dei "caratteri nazionali" (per esempio, le lettere accentate come "è"). Anche se questo tipo di caratteri si può utilizzare in un documento, è preferibile sostituirli con le corrispondenti entità SGML. Per esempio, il carattere "è" si scrive "è". È evidente che ciò rende più difficile la scrittura e, soprattutto, la lettura del testo ma, se non altro, il problema della scrittura può essere alleviato dall'uso di un editor che supporti le macro. Vi ed emacs, due editor tra i più noti, entrambi offrono la possibilità di associare macro ai tasti, generando in automatico le entità richieste. Per esempio, per ottenere automaticamente la e accentata precedente si può inserire il seguente comando nel file .exrc:

map! è è	

L'Appendice D spiega come installare gli strumenti software necessari per generare il formato HTML e gli altri formati a partire dai sorgenti DocBook. Il formato HTML è il più semplice da generare ed è utile per verificare la correttezza dei sorgenti (cioè che non vi sia qualche errore nei tag) nonché per una lettura più agevole del testo. Naturalmente, come già detto, la generazione del formato HTML non è assolutamente necessaria per effettuare la traduzione: quello che conta sono solo i sorgenti tradotti.

C.2. Inviare materiale per la guida

Chi vuole contribuire alla guida inviando materiale ha diverse possibilità, a seconda della quantità di testo che vuole scrivere. Se si tratta solo di una breve correzione o aggiunta, la cosa più semplice è inviare un'e-mail a me con il testo e provvederò a inserirlo nella guida.

Se si desidera scrivere una certa quantità di testo, come una sezione o un intero capitolo, si può scegliere tra più formati:

C.3. Schema di disposizione SGML/DocBook

Per i sorgenti della guida viene usato uno stile di formattazione simile a quello di un programma. Eccone uno schema:

<chapter id="chap-xxxxx">
  <title>Questo &egrave; il titolo di un capitolo</title>
  
  <para>
    Questo &egrave; il testo.  Questo &egrave; il testo.
    Questo &egrave; il testo.  Questo &egrave; il testo.
    Questo &egrave; il testo.
  </para>
  
  <!-- ============================================================= -->

  <sect1>
    <title>Titolo di una sect1</title>
    
    <para>
      Questo &egrave; il testo.  Questo &egrave; il testo.
      Questo &egrave; il testo.  Questo &egrave; il testo.
      Questo &egrave; il testo.
    </para>

    <!-- ........................................................... -->

    <sect2>
      <title>Titolo di una sect2</title>

      <para>
	Una sect2 &egrave; annidata dentro a una sect1.
      </para>
    </sect2>
    
  </sect1>
  
  <!-- ============================================================= -->

  <sect1>
    <title>Titolo di una sect1</title>
    
    <para>
      Questa &egrave; una lista:
      <itemizedlist>
	<listitem>
	  <para>
	    testo
	  </para>
	</listitem>
	<listitem>
	  <para>
	    testo
	  </para>
	</listitem>
      </itemizedlist>
    </para>
    
  </sect1>
</chapter>    

I default sono: