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.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.9.10. Adăugarea o notă de sponsorizare/drepturi de autor

Dacă scrieți un nou modul, o lecție sau o secțiune în numele unui sponsor, trebuie să includă un scurt mesaj, la alegerea sponsorului. Acesta trebuie să informeze cititorul despre numele sponsorului și trebuie să apară sub titlul modulului, lecției sau secțiunii sponsorizate. Totuși, mesajul nu poate consta într-o reclamă pentru compania sponsorului.

Dacă v-ați oferit voluntar să scrieți un modul, lecție sau secțiune în nume propriu și nu în numele unui sponsor, puteți include o notă de autor sub titlul modulului, lecției sau secțiunii pe care ați creat-o. Acesta trebuie să ia forma La acest [modul/lecție/secțiune] a contribuit [numele autorului]. Nu adăugați text suplimentar, detalii de contact etc. Astfel de detalii trebuie adăugate în secțiunea „Contribuitori” din Cuvânt Înainte, împreună cu nume(le) părți(lor) adăugate. Dacă ați făcut doar îmbunătățiri, corecții și/sau completări, enumerați-vă ca editor.

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.