19. Anexă: Contribuții La Acest Manual
Pentru a adăuga material în acest curs este necesar de urmărit ghidul din anexă. Nu aveți voie să alterați condițiile din Anexă dar puteți extinde cu clarificări. Acest lucru este necesar pentru siguranța calității și consistenței acestui manual.
19.1. Descărcare resurse.
Sursa acestui document se poate găsi la GitHub. Consultați GitHub.com pentru instrucțiunile de folosire a sistemului de versionare git.
19.2. Formatul Manualului
Acest manual este scris folosind Sphinx, un generator de documente Python, care folosește limbajul de marcare `reStructuredText <https://docutils.sourceforge.io/rst.html >`_ . Instrucțiuni despre cum să utilizați aceste instrumente sunt disponibile pe respectivele site-uri.
19.3. Adăugarea unui Modul
Pentru a adăuga un nou modul, mai întâi creați un nou director (direct sub nivelul superior al directorului qgis-training-manual) având numele noului modul.
În cadrul acestui nou director, creați un fișier denumit index.rst. Lăsați acest fișier gol pentru moment.
Deschideți fișierul index.rst de sub directorul de nivel superior. Primele linii sunt:
.. toctree:: :maxdepth: 2 foreword/index introduction/index
Rețineți că aceasta este o listă a numelor de directoare, urmată de denumirea index. Ea direcționează fișierul index de nivel superior spre fișierele index din fiecare director. Ordinea în care sunt listate determină ordinea pe care o vor avea în document.
Adăugați numele noului modul (adică, numele dat noului director), urmat de /index, în această listă, ori de câte ori doriți să apară modulul.
Amintiți-vă să mențineți ordinea modulelor logice, astfel încât modulele ulterioare se construiesc pe cunoștințele prezentate în modulele anterioare.
Deschideți propriul fișier index al noului modul ([module name]/index.rst).
În partea de sus a paginii, adăugați o linie de 80 de asteriscuri (*). Aceasta reprezintă un antet de modul.
La final, introducețio linie care conține expresia de marcare |MOD| (care înseamnă „modul”), urmată de numele modulului dumneavoastră.
Încheiați cu o altă linie de 80 de asteriscuri.
Lăsați o linie deschisă după aceasta.
Scrieți un scurt paragraf, explicând scopul și conținutul modulului.
Lăsați o linie deschisă, apoi adăugați următorul text:
.. toctree:: :maxdepth: 2 lesson1 lesson2
… unde lesson1, lesson2, etc., sunt numele lecțiilor planificate.
Fișierul index la nivel de modul va arăta astfel:
*******************************************************************************
|MOD| Module Name
*******************************************************************************
Short paragraph describing the module.
.. toctree::
:maxdepth: 2
lesson1
lesson2
19.4. Adăugarea unei Lecții
Pentru a adăuga o lecție pentru un modul nou sau existent:
Deschideți directorul modulului
Deschideți fișierul index.rst (creat mai sus, în cazul noilor module).
Asigurați-vă că numele lecției planificate este listat sub directiva toctree, așa cum se arată mai sus.
Creați un nou fișier în directorul modulul.
Folosiți pentru acest fișier exact același nume pe care l-ați specificat în fișierul modulului index.rst, appoi adăugați extensia .rst.
Notă
În scopuri de editare, un fișier .rst funcționează exact ca un fișier text obișnuit (.txt).
Pentru a începe scrierea lecției, scrieți fraza de marcare |LS|, urmată de numele lecției.
În următoarea linie, adăugați 80 de semne egal (=).
Lăsați o linie deschisă după aceasta.
Scrieți o scurtă descriere asupra scopului lecției.
Includeți o introducere generală în subiect. Parcurgeți lecțiile existente în acest manual, pentru exemple.
Sub aceasta, începeți un nou alineat, începând cu această frază:
**The goal for this lesson:**
Explicați pe scurt rezultatul intenționat al completării acestei lecții.
În cazul în care obiectivul lecției nu se poate descrie într-una sau două propoziții, luați în considerare împărțirea subiectului în mai multe lecții.
Fiecare lecție va fi împărțită în mai multe secțiuni, care vor fi abordate în continuare.
19.5. Adăugarea unei Secțiuni
Există două tipuri de secțiuni: „procedați în mod similar” și „încercați singuri”.
O secțiune de „urmărire” reprezintă un set detaliat de instrucțiuni, menite să învețe cititorul cum să folosească un anumit aspect din QGIS. Acest lucru se face, de obicei, oferind instrucțiuni clic cu clic, cât mai clar posibil, intercalate cu capturi de ecran.
O secțiune „încercați și dvs.” oferă cititorului o scurtă sarcină pe care să o încerce singur. De obicei, este asociată cu o înregistrare în foaia de răspuns de la sfârșitul documentației, care va arăta sau explica modul de finalizare a sarcinii și va indica rezultatul așteptat, dacă este posibil.
Fiecare secțiune vine cu un nivel de dificultate. O secțiune ușoară este notată cu |bazic|, moderată cu |moderată| și avansată cu |hard|.
19.5.1. Adăugați o secțiune „procedați în mod similar”
Pentru a începe această secțiune, scrieți fraza de marcare a nivelului de dificultate intenționat (după cum se arată mai sus).
Lăsați un spațiu și apoi scrieți |FA| (pentru „procedați în mod similar”).
Lăsați un alt spațiu și scrieți numele secțiunii (folosiți doar o literă mare, precum și majuscule pentru substantive proprii).
În linia următoare, introduceți 80 de minusuri/liniuțe (-). Asigurați-vă că editorul de text nu înlocuiește caracterul implicit pentru minus/liniuță, cu o linie mai lungă sau un alt caracter.
Scrieți o scurtă introducere a secțiunii, explicându-i scopul. Apoi oferiți instrucțiuni detaliate (clic-după-clic) privind procedura care trebuie demonstrată.
În fiecare secțiune, includeți link-uri interne, link-uri externe și capturi de ecran după cum este necesar.
Încercați să terminați fiecare secțiune cu un scurt paragraf, care să se încheie și să conducă în mod natural la secțiunea următoare, dacă este posibil.
19.5.2. Adăugați o secțiune „încercați singuri”
Pentru a începe această secțiune, scrieți fraza de marcare a nivelului de dificultate intenționat (după cum se arată mai sus).
Lăsați un spațiu și apoi scrieți |TY| (pentru „încercați singuri”).
În linia următoare, introduceți 80 de minusuri/liniuțe (-). Asigurați-vă că editorul de text nu înlocuiește caracterul implicit pentru minus/liniuță, cu o linie mai lungă sau un alt caracter.
Explicați exercițiul pe care doriți ca cititorul să-l finalizeze. Consultați secțiunile anterioare, lecțiile sau modulele, dacă este necesar.
Includeți capturi de ecran pentru a clarifica cerințele, în cazul în care o descriere textuală simplă nu este de ajuns.
În cele mai multe cazuri, veți dori să oferiți un răspuns cu privire la modul de finalizare a sarcinii propusă în această secțiune. Pentru a face acest lucru, va trebui să adăugați o intrare în foaia de răspuns.
În primul rând, decideți asupra unui nume unic pentru răspuns. În mod ideal, acest nume va include numele lecției și un număr crescător.
Creați o legătură pentru acest răspuns:
:ref:`Check your results <answer-name>`
Deschideți pagina răspunsului (answers/answers.rst).
Creați o legătură către secțiunea „încercați singuri”, prin scrierea acestei linii:
.. _answer-name:
Scrieți instrucțiunile despre modul de completare a sarcinii, folosind link-uri și imagini acolo unde este nevoie.
Pentru a încheia, includeți o legătură către secțiunea „încercați singuri”, prin scrierea acestei linii:
:ref:`Back to text <backlink-answer-name>`
Pentru a face această linie să funcționeze, includeți linia următoare deasupra antetului secțiunii „încercați singuri”:
.. _backlink-answer-name:
Rețineți că fiecare dintre aceste rânduri afișate mai sus trebuie să aibă o linie goală deasupra și dedesubt, altfel ar putea cauza erori la crearea documentului.
19.6. Adăugarea unei Concluzii
Pentru a încheia o lecție, scrieți expresia |IC| pentru «în concluzie», urmată de o nouă linie de 80 de minusuri/liniuțe (-). Scrieți o concluzie pentru lecție, explicând care concepte au fost abordate în lecție.
19.7. Adăugarea unei Secțiuni de Lecturi suplimentare
Această secțiune este opțională.
Folosiți acronimul FR în loc de „lecturi suplimentare”, urmat de o linie nouă cu 80 de minusuri/liniuțe (-).
Includeți trimiteri către site-urile externe corespunzătoare.
19.8. Adăugarea Secțiunii „Ce Urmează”
Folosiți acronimul |WN| pentru „ce urmează”, urmat de o linie nouă cu 80 de minusuri/liniuțe (-).
Explicați modul în care a pregătit această lecție studenții pentru lecția sau modulul următor.
Nu uitați să schimbați secțiunea „ce urmează” din lecția anterioară, dacă este necesar, astfel încât să se refere la noua dvs. lecție. Acest lucru va fi necesar dacă ați introdus o nouă lecție printre lecțiile existente sau după o lecție existentă.
19.9. Utilizarea Marcajelor
Pentru a adera la standardele acestui document, va trebui să adăugați marcajul standard textului dvs.
19.9.1. Noi concepte
Dacă explicați un concept nou, va trebui să scrieți numele noului concept cu caractere cursive, încadrându-l între asteriscuri (*).
This sample text shows how to introduce a *new concept*.
19.9.2. Atenție specială
Pentru a evidenția un termen esențial, care nu reprezintă un concept nou, scrieți termenul cu caractere aldine, încadrându-l între asteriscuri duble (**).
Folosiți-le cu moderație! Dacă utilizați prea multe, cititorul ar putea avea impresia că strigați sau ca aveți un aer de superioritate.
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. Imagini
Când adăugați o imagine, salvați-o în folderul _static/lesson_name/.
Includeți-l în document, în felul următor:
.. figure:: img/image_file.extension :align: center
Nu uitați să lăsați o linie, deasupra și dedesubtul marcajului imaginii.
19.9.4. Legături interne
Pentru a crea o ancoră pentru un link, scrieți următoarea linie deasupra locului către care doriți să indice linkul:
.. _link-name:
Pentru a crea o legătură, adăugați această linie:
:ref:`Descriptive link text <link-name>`
Nu uitați să lăsați o linie, deasupra și dedesubtul acestei linii.
19.9.5. Legături externe
Pentru a crea o legătură externă, scrieți-o astfel:
`Descriptive link text <link-url>`_
Nu uitați să lăsați o linie, deasupra și dedesubtul acestei linii.
19.9.6. Utilizați text monospațiat
Când scrieți un text pe care utilizatorul trebuie să îl introducă, un nume de cale sau numele unui element de bază de date, cum ar fi un nume de tabelă sau de coloană, trebuie să îl scrieți în text monospațiat. De exemplu:
Enter the following path in the text box: :kbd:`path/to/file`.
19.9.7. Etichetarea elementelor GUI
Dacă vă referiți la un element GUI, cum ar fi un buton, trebuie să scrieți numele acestuia în formatul etichetei GUI. De exemplu:
To access this tool, click on the :guilabel:`Tool Name` button.
Acest lucru se aplică, de asemenea, dacă menționați numele unui instrument fără a cere utilizatorului să efectueze clic pe un buton.
19.9.9. Adăugarea notelor
Este posibil să vă trebuiască introducerea unui text sub formă de notă, în care să oferiți detalii suplimentare care nu reies cu ușurință din fluxul lecției. Acesta este marcajul:
[Normal paragraph.] .. note:: Note text. New line within note. New paragraph within note. [Unindented text resumes normal paragraph.]
19.10. Mulțumiri!
Vă mulțumim pentru contribuția la acest proiect! Procedând astfel, faceți QGIS mai accesibil pentru utilizatori și adăugați valoare întregului proiect QGIS.