Importante

unireLa traduzione è uno sforzo comunitario you can join. Questa pagina è attualmente tradotta al 100.00%.

19. Appendice: Contribuire a questo Manuale

Per aggiungere materiale a questo corso, devi seguire le linee guida contenute in questa Appendice. Non ti è permesso di modificare le regole di questa Appendice, se non per motivi di maggiore chiarezza. Questo per garantire la qualità e la coerenza del manuale.

19.1. Scaricare Risorse

La fonte di questo documento è disponibile su GitHub. Consultare GitHub.com per istruzioni su come utilizzare il sistema git di controllo della versione.

19.2. Formato del Manuale

Questo manuale è stato scritto utilizzando Sphinx, un generatore di documenti Python che utilizza il linguaggio di markup reStructuredText. Le istruzioni per l’uso di questi strumenti sono disponibili sui rispettivi siti.

19.3. Aggiungere un Modulo

Per aggiungere un nuovo modulo:

1. Per prima cosa crea una nuova cartella (direttamente sotto il livello superiore della cartella qgis-training-manual) con il nome del nuovo modulo.

2. In questa nuova cartella, crea un file chiamato index.rst. Lascia questo file vuoto per ora.

3. Apri il file index.rst nel primo livello della cartella. Le prime righe sono:

   .. toctree::
      :maxdepth: 2
   
      foreword/index
      introduction/index
   

Noterai che si tratta di un elenco di nomi di cartelle, seguito dal nome index. Questo indirizza il file di indice di primo livello ai file di indice di ciascuna cartella. L’ordine in cui sono elencati determina l’ordine che avranno nel documento.

1. Aggiungi il nome del tuo nuovo modulo (cioè il nome che hai dato alla nuova cartella), seguito da /index, a questo elenco, ovunque vuoi che il tuo modulo appaia.

2. Ricordati di mantenere logico l’ordine dei moduli, in modo tale che i moduli successivi si basino sulla conoscenza presentata nei moduli precedenti.

3. Apri il file indice del nuovo modulo (nome_modulo/index.rst).

4. Nella parte superiore della pagina, crea l’intestazione del modulo:

   1. scrivi una prima riga di asterischi (*).

   2. Dopo questa una riga contenente la frase di markup Module:, seguita dal nome del modulo.

   3. A chiusura un’altra riga con lo stesso numero di asterischi.

   Nota

   La sottolineatura e la sovratitolazione non devono essere più corte della riga contenente il titolo del modulo.

5. Lascia una linea aperta sotto questo.

6. Scrivi un breve paragrafo che spieghi lo scopo e il contenuto del modulo.

7. Lascia una riga aperta, quindi aggiungi il testo seguente:

   .. toctree::
      :maxdepth: 2
   
      lesson1
      lesson2
   

   … dove lesson1, lesson2, ecc. sono i nomi delle tue lezioni progettate.

Il file di indice a livello di modulo sarà simile a questo:

*******************************************************************************
Module: Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2

   lesson1
   lesson2

19.4. Aggiungere una Lezione

Aggiungere una lezione ad un nuovo o esistente modulo:

1. Apri la directory del modulo.

2. Apri il file index.rst (creato in precedenza nel caso di nuovi moduli).

3. Assicurati che il nome della lezione programmata sia elencato sotto la clausola toctree, come mostrato sopra.

4. Crea un nuovo file nella cartella del modulo.

5. Nomina questo file esattamente come il nome fornito nel file index.rst del modulo e aggiungi l’estensione .rst.

Nota

Ai fini della modifica, un file .rst funziona esattamente come un normale file di testo (.txt).

1. Per iniziare a scrivere la lezione, scrivi la frase di markup Lesson, seguita dal nome della lezione.

2. Nella riga successiva, scrivi una riga di segni uguali (=), non più corta del titolo della lezione.

3. Lascia una linea aperta dopo questo.

4. Scrivi una breve descrizione dello scopo previsto della lezione.

5. Includi un’introduzione generale all’argomento. Vedere le lezioni esistenti in questo manuale per esempi.

6. Sotto questo, inizia un nuovo paragrafo, iniziando con questa frase:

   **The goal for this lesson:**
   

7. Spiega brevemente il risultato previsto dal completamento di questa lezione.

8. Se non riesci a descrivere l’obiettivo della lezione in una o due frasi, valuta la possibilità di suddividere l’argomento in più lezioni.

Ogni lezione sarà suddivisa in più sezioni, che verranno affrontate successivamente.

19.5. Aggiungere una Sezione

Esistono due tipi di sezioni: «seguire» e «prova tu stesso».

• Una sezione «seguire» è un insieme dettagliato di istruzioni intese a insegnare al lettore come utilizzare un dato aspetto di QGIS. Questo viene in genere fatto fornendo indicazioni clic-by-clic il più chiaramente possibile, intervallate da screenshot.

• Una sezione “Prova tu stesso” offre al lettore un breve compito da svolgere da solo. Di solito è associata a una voce nella casella di risposta sottostante, che mostrerà o spiegherà come completare il compito e mostrerà il risultato atteso, se disponibile.

Ogni sezione ha un livello di difficoltà. Una sezione facile è indicata con ★☆☆, moderata con ★★☆ e avanzata con ★★★.

19.5.1. Aggiungere una sezione «seguire»

1. Per iniziare questa sezione, scrivi la frase di markup del livello di difficoltà previsto (come mostrato sopra).

2. Lascia uno spazio e poi scrivi Segui passo passo.

3. Lascia un altro spazio e scrivi il nome della sezione (usa solo una lettera maiuscola iniziale, così come le maiuscole per i nomi propri).

4. Nella riga successiva, scrivi una riga di minuscoli trattini (-), non più corti del titolo della sezione.

5. Scrivi una breve introduzione alla sezione, spiegandone lo scopo. Quindi fornisci istruzioni dettagliate (clic per clic) sulla procedura da seguire.

6. In ogni sezione, includie link interni, link esterni e screenshot secondo necessità.

7. Cerca di terminare ogni sezione con un breve paragrafo che la concluda e conduca naturalmente alla sezione successiva, se possibile.

19.5.2. Aggiungere una sezione «prova tu stesso»

1. Per iniziare questa sezione, scrivi la frase di markup del livello di difficoltà previsto (come mostrato sopra).

2. Lascia uno spazio e scrivi ``Prova tu:””.

3. Nella riga successiva, scrivi una riga di minuscoli trattini (-), non più corti del titolo della sezione.

4. Spiega l’esercizio che vuoi che il lettore completi. Se necessario, fai riferimento alle sezioni, lezioni o moduli precedenti.

5. Includi screenshot per chiarire i requisiti se una semplice descrizione testuale non è chiara.

Nella maggior parte dei casi, vorrai fornire una risposta su come completare il compito dato in questa sezione. Per farlo, devi creare e inserire un blocco di risposte sotto le istruzioni.

1. Per prima cosa, crea il widget collassabile personalizzato che contiene la risposta:

   .. admonition:: Answer
      :class: dropdown
   

2. Mantenendo una rientranza rispetto al blocco precedente, scrivi le istruzioni su come completare il compito, utilizzando link e immagini dove necessario.

19.6. Aggiungere una conclusione

Per concludere una lezione:

1. Scrivi la frase In conclusione, seguita da una nuova riga di minuscoli trattini (-).

2. Scrivi una sintesi della lezione, spiegando quali concetti sono stati trattati nella lezione.

19.7. Aggiungere un’ulteriore sezione di lettura

Questa sezione è facoltativa.

• Scrivi la frase “Ulteriori Letture”, seguita da una nuova riga di minuscoli trattini (-).

• Includi collegamenti a siti Web esterni appropriati.

19.8. Aggiungere una Sezione Cosa c’è Dopo

1. Scrivi la frase Che cosa c'è dopo?, seguita da una nuova riga di minuscoli trattini (-).

2. Spiega come questa lezione ha preparato gli studenti per la lezione o il modulo successivo.

3. Ricordati di cambiare la sezione «cosa c’è dopo» della lezione precedente, se necessario, in modo che si riferisca alla tua nuova lezione. Ciò sarà necessario se hai inserito una nuova lezione tra lezioni esistenti o dopo una lezione esistente.

19.9. Usare Markup

Per aderire agli standard di questo documento, dovrai aggiungere un markup standard al tuo testo.

19.9.1. Nuovi concetti

Se stai spiegando un nuovo concetto, dovrai scrivere il nome del nuovo concetto in corsivo, racchiudendolo tra asterischi (*).

This sample text shows how to introduce a *new concept*.

19.9.2. Enfasi

• Per evidenziare un termine importante che non è un concetto nuovo, scrivilo in grassetto racchiudendolo tra doppi asterischi (**).

• Usalo con parsimonia! Se usato troppo, può sembrare al lettore che tu stia gridando o sei troppo esigente.

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. Immagini

• Quando aggiungo un’immagine, salvala in una cartella img insieme al file della lezione.

• Includila nel documento in questo modo:

  .. figure:: img/image_file.extension
     :align: center
  

• Ricordati di lasciare una linea aperta sopra e sotto il markup dell’immagine.

19.9.4. Collegamenti interni

• Per creare un ancoraggio per un collegamento, scrivi la riga seguente sopra il punto in cui desideri che il collegamento punti:

  .. _link-name:
  

• Ricordati di lasciare una linea aperta sopra e sotto questa linea.

• Per creare un collegamento, fai riferimento ad esso come segue:

  :ref:`Descriptive link text <link-name>`
  

19.9.5. Collegamenti Esterni

• Per creare un collegamento esterno, scrivilo in questo modo:

  `Descriptive link text <link-url>`_
  

19.9.6. Usare testo monospazio

• Quando scrivi un testo che l’utente deve immettere, un nome di percorso o il nome di un elemento del database, come il nome di una tabella o di una colonna, devi scriverlo in testo monospaziato. Ad esempio:

  Enter the following path in the text box: ``path/to/file``.
  

19.9.7. Etichettare gli elementi della GUI

• Se ti riferisci a un elemento della GUI, come un pulsante, devi scrivere il suo nome in the GUI label format. Per esempio:

  To access this tool, click on the :guilabel:`Tool Name` button.
  

• Questo vale anche se stai citando il nome di uno strumento senza richiedere all’utente di fare clic su un pulsante.

19.9.8. Selezione Menu

• Se stai guidando un utente attraverso i menu, devi usare menu ► selection ► format. Per esempio:

  To use the :guilabel:`Tool Name` tool, go to :menuselection:`Plugins -->
  Tool Type --> Tool Name`.
  

19.9.9. Aggiunta di note

• Potresti aver bisogno di aggiungere una nota nel testo, che spieghi i dettagli extra che non possono essere facilmente inseriti nel contesto della lezione. Questo è il markup:

  [Normal paragraph.]
  
  .. note:: Note text.
    New line within note.
  
    New paragraph within note.
  
  [Unindented text resumes normal paragraph.]
  

19.9.10. Aggiunta di una nota di sponsorizzazione/paternità

Se stai scrivendo un nuovo modulo, lezione o sezione per conto di uno sponsor, devi includere un breve messaggio dello sponsor a sua scelta. Questo deve notificare al lettore il nome dello sponsor e deve apparire sotto l’intestazione del modulo, della lezione o della sezione che ha sponsorizzato. Tuttavia, dovrebbe non sembrare una pubblicità per la loro azienda.

Se ti sei offerto di scrivere un modulo, una lezione o una sezione a titolo personale, e non per conto di uno sponsor, puoi inserire una nota di paternità sotto l’intestazione del modulo, della lezione o della sezione di cui sei autore. Tale nota deve avere la forma Questo [modulo/lezione/sezione] è stato realizzato da [nome dell'autore]. Non aggiungere altro testo, dettagli di contatto, ecc. Tali dettagli devono essere inseriti nella sezione “Contributori” della prefazione, insieme al nome della parte o delle parti aggiunte. Se hai apportato solo miglioramenti, correzioni e/o aggiunte, inserisciti come redattore.

19.10. Grazie!

Grazie per aver contribuito a questo progetto! In questo modo, stai rendendo QGIS più accessibile agli utenti e aggiungendo valore al progetto QGIS nel suo complesso.