19. Appendix: 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 <https://github.com/qgis/QGIS-Documentation> _. Consultare GitHub.com <https://github.com/> _ per istruzioni su come utilizzare il sistema git di controllo della versione.
19.2. Formato del Manuale
Questo manuale è stato scritto usando Sphinx <https://www.sphinx-doc.org/en/master/> _, un generatore di documenti Python che usa `reStructuredText <http://docutils.sourceforge.net/rst.html > `_ linguaggio di markup. Le istruzioni su come utilizzare questi strumenti sono disponibili sui rispettivi siti.
19.3. Aggiungere un Modulo
Per aggiungere un nuovo modulo, creare prima una nuova directory (direttamente sotto il livello superiore della directory: kbd: qgis-training-manual) con il nome del nuovo modulo.
In questa nuova directory, create un file chiamato: kbd: index.rst. Lasciate vuoto questo file per ora.
Aprite il file: kbd: index.rst nella directory di primo livello. Le sue prime righe sono:
.. toctree:: :maxdepth: 2 foreword/index introduction/index
Noterete che questo è un elenco di nomi di directory, seguito dal nome: kbd: index. Ciò indirizza il file di indice di primo livello ai file di indice in ciascuna directory. L’ordine in cui sono elencati determina l’ordine che avranno nel documento.
Aggiungete il nome del tuo nuovo modulo (cioè il nome che avete dato alla nuova directory), seguito da / index, a questo elenco, ovunque voi vogliate che il vostro modulo appaia.
Ricordarsi di mantenere logico l’ordine dei moduli, in modo tale che i moduli successivi si basino sulla conoscenza presentata nei moduli precedenti.
Aprite il file indice del vostro nuovo modulo (: kbd: [nome modulo] / index.rst).
Nella parte superiore della pagina, scrivete una riga di 80 asterischi (*). Questo rappresenta un’intestazione del modulo.
Seguitela con una riga contenente la frase di markup |MOD| (che sta per «module»), seguita dal nome del vostro modulo.
Terminatela con un’altra riga di 80 asterischi.
Lasciate una linea aperta sotto questo.
Scrivete un breve paragrafo che spieghi lo scopo e il contenuto del modulo.
Lasciate 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:
Aprire la directory del modulo.
Apri il file index.rst (creato sopra nel caso di nuovi moduli).
Assicuratevi che il nome della lezione pianificata sia elencato sotto la direttiva toctree, come mostrato sopra.
Create un nuovo file nella directory del modulo.
Assegnate un nome a questo file esattamente come il nome fornito nel file index.rst del modulo e aggiungete 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, scrivete la frase di markup |LS|, seguita dal nome della lezione.
Nella riga successiva, scrivete una riga di 80 segni di uguale (=).
Lasciate una linea aperta dopo questo.
Scrivete una breve descrizione dello scopo previsto della lezione.
Includere 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:**
Spiegate brevemente il risultato previsto dal completamento di questa lezione.
Se non riuscite a descrivere l’obiettivo della lezione in una o due frasi, valutate 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: «segui» 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 click-by-click 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 l’incarico 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 «segui»
Per iniziare questa sezione, scrivere la frase di markup del livello di difficoltà previsto (come mostrato sopra).
Lasciate uno spazio e scrivete |FA| (per «segui»).
Lasciate un altro spazio e scrivete il nome della sezione (usate solo una lettera maiuscola iniziale, così come le maiuscole per i nomi propri).
Nella riga successiva, scrivete una riga di 80 meno / trattini (-). Assicuratevi che il vostro editor di testo non sostituisca il carattere meno/trattino predefinito con un trattino lungo o un altro carattere.
Scrivete una breve introduzione alla sezione, spiegandone lo scopo. Quindi fornire istruzioni dettagliate (clic per clic) sulla procedura da dimostrare.
In ogni sezione, includete link interni, link esterni e screenshot secondo necessità.
Cercate di terminare ogni sezione con un breve paragrafo che la concluda e conduca naturalmente alla sezione successiva, se possibile.
19.5.2. Aggiunta di una sezione «prova tu stesso»
Per iniziare questa sezione, scrivere la frase di markup del livello di difficoltà previsto (come mostrato sopra).
Lasciate uno spazio e scrivete |TY| (per «prova tu stesso»).
Nella riga successiva, scrivete una riga di 80 meno / trattini (-). Assicuratevi che il vostro editor di testo non sostituisca il carattere meno/trattino predefinito con un trattino lungo o un altro carattere.
Spiegate l’esercizio che volete che il lettore completi. Se necessario, fare riferimento alle sezioni, lezioni o moduli precedenti.
Includete screenshot per chiarire i requisiti se una semplice descrizione testuale non è chiara.
Nella maggior parte dei casi, vorrete fornire una risposta su come completare il compito fornito in questa sezione. Per fare ciò, dovrete aggiungere una voce nel foglio delle risposte.
Per prima cosa, decidete 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 foglio delle risposte (answer/answer.rst).
Crea un collegamento alla sezione «prova tu stesso» scrivendo questa riga:
.. _answer-name:
Scrivete le istruzioni su come completare il compito, utilizzando link e immagini dove necessario.
Per terminare, includete un link alla sezione «prova tu stesso» scrivendo questa riga:
:ref:`Back to text <backlink-answer-name>`
Per far funzionare questo collegamento, aggiungete 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, scrivete la frase: kbd:|IC| per «in conclusione», seguita da una nuova riga di 80 meno / trattini (-). Scrivete una conclusione per la lezione, spiegando quali concetti sono stati trattati nella lezione.
19.7. Aggiungere un’ulteriore sezione di lettura
Questa sezione è facoltativa.
Scrivete la frase: kbd:FR per» ulteriori letture «, seguita da una nuova riga di 80 meno / trattini (-).
Includere collegamenti a siti Web esterni appropriati.
19.8. Aggiungere una Sezione Cosa c’è Dopo
Scrivete la frase: kbd:|WN| per «qual è il prossimo», seguita da una nuova riga di 80 meno / trattini (-).
Spiegate come questa lezione ha preparato gli studenti per la lezione o il modulo successivo.
Ricordate di cambiare la sezione «cosa c’è dopo» della lezione precedente, se necessario, in modo che si riferisca alla vostra nuova lezione. Ciò sarà necessario se avete inserito una nuova lezione tra lezioni esistenti o dopo una lezione esistente.
19.9. Usare Markup
Per aderire agli standard di questo documento, dovrete aggiungere un markup standard al vostro testo.
19.9.1. Nuovi concetti
Se state spiegando un nuovo concetto, dovrete 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 (**).
Usaltelo con parsimonia! Se usato troppo, al lettore può sembrare che voi stiate gridando o siate condiscendenti.
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 si aggiunge un’immagine, salvarla nella cartella _static/lesson_name/.
Includetelo nel documento in questo modo:
.. figure:: img/image_file.extension :align: center
Ricordate 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, aggiungete questa linea:
:ref:`Descriptive link text <link-name>`
Ricordate di lasciare una linea aperta sopra e sotto questa linea.
19.9.5. Collegamenti Esterni
Per creare un collegamento esterno, scrivetelo in questo modo:
`Descriptive link text <link-url>`_
Ricordate di lasciare una linea aperta sopra e sotto questa linea.
19.9.6. Usare testo monospazio
Quando scrivete 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 vi riferirite a un elemento della GUI, come un pulsante, dovete scrivere il suo nome in: guilabel: the GUI label format. Per esempio:
To access this tool, click on the :guilabel:`Tool Name` button.
Questo vale anche se state citando il nome di uno strumento senza richiedere all’utente di fare clic su un pulsante.
19.9.9. Aggiunta di note
Potreste 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.