Appendix B. Contribuire alla guida a NetBSD

Table of Contents

B.1. Tradurre la guida
B.1.1. Che cosa serve per iniziare una traduzione ?
B.1.2. Scrivere in XML/DocBook
B.2. Inviare i contributi
B.3. Schema XML/DocBook

C'è un interesse sia per la documentazione introduttiva che per la documentazione avanzata su NetBSD: questo è probabilmente un segno dell'aumento della popolarità di questo sistema operativo e un aumento dalla sua base utenti. Perciò è importante continuare ad aggiungere nuovo materiale su questa guida e migliorare i testi presenti.

Qualunque sia il tuo livello di esperienza con NetBSD, puoi contribuire allo sviluppo di questa guida. Questa appendice spiega come e cosa devi conoscere prima di iniziare.

Se sei un principiante e hai trovato questa guida di aiuto, invia commenti e consigli a . Per esempio se hai provato qualche cosa descritto qui e non ha funzionato nel tuo caso o pensi che qualche cosa non è descritta chiaramente o se hai un'idea per un nuovo capitolo, ecc.: questo tipo di feedback è molto utile.

Se sei un utente intermedio o avanzato, considera di contribuire a nuovi materiali di questa guida: potresti scrivere un nuovo capitolo o migliorare quelli esistenti.

Se hai un po' di tempo libero potresti tradurre la guida in un altre lingue.

Indipendentemente da ciò che scegli, non inziare senza prima averci contattato, in modo tale da evitare di lavorare sullo stesso materiale.

B.1. Tradurre la guida

Se vuoi tradurre la guida la prima cosa da fare è, come si è precedentemente detto, contattare o scrivere alla mailing list . Ci sono diverse possibili situazioni:

  • qualcun altro sta lavorando sulla traduzione nella tua lingua; potresti aiutarlo.

  • nessuno sta correntemente lavorando su una traduzione nella tua lingua, ma qualche capitolo è già stato tradotto e puoi tradurre i capitoli rimanenti.

  • inizi una nuova traduzione. Certamente non devi tradurre tutta la guida: è un grosso lavoro, me se inizi a tradurre uno o due capitoli sarà un buon punto di partenza per qualcun altro.

Anche se una traduzione è già disponibile, è sempre necessario mantenerla aggiornata quando viene aggiunto un nuovo materiale o vengono fatte correzioni. Potresti diventare il maintainer della traduzione.

B.1.1. Che cosa serve per iniziare una traduzione ?

Tutto quello di cui hai bisogno sinteticamente è:

  • i sorgenti della guida. Fanno parte di “htdocs”, scaricali dal CVS (anonimo) come se stessi scaricando “src” o “pkgsrc” come descritto su Chapter 29, Obtaining the sources.

  • un editor di testi, come ad esempio vi o emacs.

Important

Non iniziare a lavorare con HTML o altri formati: sarà molto difficile convertire il tuo lavoro in XML/DocBook, il formato utilizzato dalla Guida a NetBSD.

B.1.2. Scrivere in XML/DocBook

Per tradurre la guida non necessiti di imparare XML/DocBook; procurati i sorgenti della Guida a NetBSD e lavora direttamente su quelli, in modo tale da riutilizzare gli stessi formati (cioè tag) nella tua traduzione. Per esempio per tradurre la nota precedente, dovrai:

  1. aprire con il tuo editor il sorgente inglese del capitolo corrente, ap-contrib.xml.

  2. trovare il testo della nota precedente. Osserverai qualche cosa del tipo:

    <important>
      <para>
        Non iniziare a lavorare con HTML o altri formati: sarà molto
        difficile convertire il tuo lavoro in XML/DocBook, il formato
        utilizzato dalla Guida a NetBSD.
      </para>
    </important>
  3. aggiungi la tua traduzione tra i tag, dopo la versione in inglese. Il nuovo testo avrà un aspetto del tipo:

    <important>
      <para>
        Non iniziare a lavorare con HTML o altri formati: sarà molto
        difficile convertire il tuo lavoro in XML/DocBook, il formato
        utilizzato dalla Guida a NetBSD.
        la tua traduzione va qui
        la tua traduzione va qui
        la tua traduzione va qui
      </para>
    </important>
  4. elimina le quattro righe in italiano tra le tag lasciando la tua traduzione.

    <important>
      <para>
        la tua traduzione va qui
        la tua traduzione va qui
        la tua traduzione va qui
      </para>
    </important>

Quando scrivi la traduzione utilizza la stessa indentazione e lo stesso stile di formattazione del testo originale. Vedi Section B.3, “Schema XML/DocBook” per un esempio.

Un problema che probabilmente affronterai mentre scrivi testo in DocBook è quello con i caratteri nazionali (per esempio lettere accentate come “è”). Puoi utilizzare questi caratteri nel sorgente ma è preferibile sostiutirli con entità XML. Per esempio, “è” si scrive “&egrave;”. Certamente questo fa si che il testo sorgente sia più difficile da scrivere e leggere; il primo problema, scrivere, può essere risolto utilizzando un buon editor che supporti le macro. Vi ed emacs, che sono delle scelte molto popolari hanno entrambi questa caratteristica e puoi mappare i tasti accentati della tua tastiera per generare le entità automaticamente. Per esempio, per vi puoi mettere una riga simile alla seguente nel tuo file .exrc:

map! è &egrave;

Appendix C, Getting started with XML/DocBook illustra come installare i software necessari per generare HTML e altri formati dai sorgenti DocBook. È utile se vuoi controllare il tuo lavoro (per esempio accertarti di non aver inavvertitamente tolto qualche tag) o per vedere come appare, ma non è un requisito per una traduzione. Se non vuoi installare questi software, invia le tue patch e sorgenti a : li controlleremo e produrremo i vari formati.

B.2. Inviare i contributi

Se vuoi contribuire con qualche materiale alla guida hai diverse opzioni, dipende da quanto testo vuoi scrivere. Se vuoi inviare solo una piccola correzione il modo più semplice è inviarla a tramite e-mail. Se hai intenzione di scrivere una quantità sostanziosa di testo, come una sezione o un capitolo, puoi scegliere tra diversi formati:

  • XML/DocBook; questo è il formato preferito. Se scegli di utilizzare questo formato, ottieni i sorgenti della guida e utilizzali come schema per l'indentazione e il formato e come disposizione del testo, in maniera tale da lasciare la formattazione coerente.

  • text; se la formattazione del testo è semplice, non sarà difficile la conversione del testo al formato XML.

  • altri formati sono accettati se non puoi veramente utilizzare nessuno tra i precedenti.

B.3. Schema XML/DocBook

Per la guida si utilizza 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 di un paragrafo. Questo
      <egrave> il testo di un paragrafo.
    Questo <egrave> il testo di un paragrafo. Questo
      <egrave> il testo di un paragrafo.
    Questo <egrave> il testo di un paragrafo.
  </para>

  <!-- ============================================================= -->

  <sect1>
    <title>Questo <egrave> il titolo di una
      sect1</title>

    <para>
      Questo <egrave> il testo di un paragrafo. Questo
        <egrave> il testo di un paragrafo.
      Questo <egrave> il testo di un paragrafo. Questo
        <egrave> il testo di un paragrafo.
      Questo <egrave> il testo di un paragrafo.
    </para>

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

    <sect2>
      <title>Questo <egrave> il titolo di una
	      sect2</title>

      <para>
	Una sect2 <egrave> annidiata dentro a una sect1.
      </para>
    </sect2>

  </sect1>

  <!-- ============================================================= -->

  <sect1>
    <title>Questo <egrave> il titolo di un altra
	    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:

  • due spazi per ogni livello di indentazione

  • linee non più lunghe di 72 caratteri.

  • usare linee di separazione (commenti) tra sect1/sect2.