19. Appendice: Contribuire a questo Manuale
Per aggiungere materiali a questo corso, è necessario seguire le linee guida in questa Appendice. Non dovete modificare le condizioni in questa Appendice se non per chiarimenti. Questo per garantire che la qualità e la coerenza di questo manuale possano essere mantenute.
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, crea prima una nuova cartella (direttamente sotto il livello superiore della cartella qgis-training-manual) con il nome del nuovo modulo.
In questa nuova cartella, crea un file chiamato index.rst. Lascia vuoto questo file per ora.
Apri il file index.rst nella cartella di primo livello. Le sue prime righe sono:
.. toctree:: :maxdepth: 2 foreword/index introduction/index
Noterai che questo è un elenco di nomi di cartelle, seguito dal nome : kbd:index. Ciò indirizza il file di indice di primo livello ai file di indice in ciascuna cartella. L’ordine in cui sono elencati determina l’ordine che avranno nel documento.
Aggiungi il nome del tuo nuovo modulo (cioè il nome che hai dato alla nuova directory), seguito da /index, a questo elenco, ovunque vuoi che il tuo modulo appaia.
Ricordati di mantenere logico l’ordine dei moduli, in modo tale che i moduli successivi si basino sulla conoscenza presentata nei moduli precedenti.
Apri il file indice del tuo nuovo modulo (: kbd: [nome modulo] / index.rst).
Nella parte superiore della pagina, scrivi una riga di 80 asterischi (*). Questo rappresenta un’intestazione del modulo.
Seguita da una riga contenente la frase di markup |MOD| (che sta per «module»), seguita dal nome del tuo modulo.
Termina con un’altra riga di 80 asterischi.
Lascia una linea aperta sotto questo.
Scrivi un breve paragrafo che spieghi lo scopo e il contenuto del modulo.
Lascia una riga aperta, quindi aggiungi il testo seguente:
.. toctree:: :maxdepth: 2 lesson1 lesson2
… dove lesson1,:kbd:lesson2, ecc. sono i nomi delle lezioni pianificate.
Il file di indice a livello di modulo sarà simile a questo:
*******************************************************************************
|MOD| 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:
Apri la directory del modulo.
Apri il file index.rst (creato sopra nel caso di nuovi moduli).
Assicurati che il nome della lezione pianificata sia elencato sotto la direttiva toctree, come mostrato sopra.
Crea un nuovo file nella cartella del modulo.
Assegna un nome a questo file esattamente come il nome fornito nel file index.rst del modulo e aggiungi l’estensione .rst.
Nota
Per scopi di modifica, un file .rst funziona esattamente come un normale file di testo (.txt)
Per iniziare a scrivere la lezione, scrivi la frase di markup |LS|, seguita dal nome della lezione.
Nella riga successiva, scrivi una riga di 80 segni di uguale (=).
Lascia una linea aperta dopo questo.
Scrivi una breve descrizione dello scopo previsto della lezione.
Includi un’introduzione generale all’argomento. Vedere le lezioni esistenti in questo manuale per esempi.
Sotto questo, inizia un nuovo paragrafo, iniziando con questa frase:
**The goal for this lesson:**
Spiega brevemente il risultato previsto dal completamento di questa lezione.
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 per provare da solo. Di solito è associata a una voce nel foglio delle risposte alla fine della documentazione, che mostrerà o spiegherà come completare il compito e mostrerà il risultato atteso se possibile.
Ogni sezione ha un livello di difficoltà. Una sezione facile è indicata da |basic|, moderata da |moderate| e avanzata da |hard|.
19.5.1. Aggiungere una sezione «seguire»
Per iniziare questa sezione, scrivi la frase di markup del livello di difficoltà previsto (come mostrato sopra).
Lascia uno spazio e scrivi |FA| (per «seguire»).
Lascia un altro spazio e scrivi il nome della sezione (usa solo una lettera maiuscola iniziale, così come le maiuscole per i nomi propri).
Nella riga successiva, scrivi una riga di 80 meno/trattini (-). Assicurati che il tuo editor di testo non sostituisca il carattere meno/trattino predefinito con un trattino lungo o un altro carattere.
Scrivi una breve introduzione alla sezione, spiegandone lo scopo. Quindi fornisci istruzioni dettagliate (clic per clic) sulla procedura da seguire.
In ogni sezione, includie link interni, link esterni e screenshot secondo necessità.
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»
Per iniziare questa sezione, scrivi la frase di markup del livello di difficoltà previsto (come mostrato sopra).
Lascia uno spazio e scrivi |TY| (per «prova tu stesso»).
Nella riga successiva, scrivi una riga di 80 meno/trattini (-). Assicurati che il tuo editor di testo non sostituisca il carattere meno/trattino predefinito con un trattino lungo o un altro carattere.
Spiega l’esercizio che vuoi che il lettore completi. Se necessario, fai riferimento alle sezioni, lezioni o moduli precedenti.
Includi screenshot per chiarire i requisiti se una semplice descrizione testuale non è chiara.
Nella maggior parte dei casi, vorresti fornire una risposta su come completare il compito fornito in questa sezione. Per fare ciò, dovrai aggiungere una voce nel modulo delle risposte.
Per prima cosa, decidi un nome univoco per la risposta. Idealmente, questo nome includerà il nome della lezione e un numero crescente.
Crea un collegamento per questa risposta:
:ref:`Check your results <answer-name>`
Apri il modulo delle risposte (answer/answer.rst).
Crea un collegamento alla sezione «prova tu stesso» scrivendo questa riga:
.. _answer-name:
Scrivi le istruzioni su come completare il compito, utilizzando link e immagini dove necessario.
Per terminare, includi un link alla sezione «prova tu stesso» scrivendo questa riga:
:ref:`Back to text <backlink-answer-name>`
Per far funzionare questo collegamento, aggiungi la seguente riga sopra l’intestazione alla sezione «prova tu stesso»:
.. _backlink-answer-name:
Ricorda che ognuna di queste righe mostrate sopra deve avere una riga vuota sopra e sotto di essa, altrimenti potrebbe causare errori durante la creazione del documento.
19.6. Aggiungere una conclusione
Per terminare una lezione, scrivi la frase |IC| per «in conclusione», seguita da una nuova riga di 80 meno/trattini (-). Scrivi una conclusione per la lezione, spiegando quali concetti sono stati trattati nella lezione.
19.7. Aggiungere un’ulteriore sezione di lettura
Questa sezione è facoltativa.
Scrivi la frase FR per «ulteriori letture», seguita da una nuova riga di 80 meno / trattini (-).
Includi collegamenti a siti Web esterni appropriati.
19.8. Aggiungere una Sezione Cosa c’è Dopo
Scrivi la frase |WN| per «cosa c’è dopo», seguita da una nuova riga di 80 meno/trattini (-).
Spiega come questa lezione ha preparato gli studenti per la lezione o il modulo successivo.
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 enfatizzare un termine cruciale che non è un nuovo concetto, scrivi il termine 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 aggiungi un’immagine, salvala nella cartella _static/lesson_name/.
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:
Per creare un collegamento, aggiungi questa linea:
:ref:`Descriptive link text <link-name>`
Ricordati di lasciare una linea aperta sopra e sotto questa linea.
19.9.5. Collegamenti Esterni
Per creare un collegamento esterno, scrivilo in questo modo:
`Descriptive link text <link-url>`_
Ricordati di lasciare una linea aperta sopra e sotto questa linea.
19.9.6. Usare testo monospazio
Quando scrivi del testo che l’utente deve inserire, 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 monospaced text. Per esempio:
Enter the following path in the text box: :kbd:`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.9. Aggiunta di note
Potresti aver bisogno di una nota nel testo, che spieghi dettagli extra che non possono essere facilmente inseriti nel flusso della lezione. Questo è il markup:
[Normal paragraph.] .. note:: Note text. New line within note. New paragraph within note. [Unindented text resumes normal paragraph.]
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.