Outdated version of the documentation. Find the latest one here.

Handleiding voor documentatie

Introductie

De documentatie voor QGIS zal automatisch op de server worden gebouwd om 0, 8am, 4pm PDT (Pacific Daylight Time). De huidige status is beschikbaar op http://docs.qgis.org.

DocumentatiE voor QGIS wordt voornamelijk geschreven met behulp van de indeling voor de syntaxis reStructuredText (reST), gekopeld aan enkele scripts uit de programmaset Sphinx om de uitvoer naar HTML na te bewerken. Bekijk http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html of http://sphinx.pocoo.org/markup/inline.html.

Volg in het algemeen, bij het maken van documentatie in rst voor het project QGIS, de Python documentation style guide lines. Hieronder worden enkele algemene richtlijnen weergegeven die kunnen worden gevolgd bij het gebruiken van reST voor het schrijven van de documentatie voor QGIS.

Als u zoekt naar algemene regels om bij te dragen aan het project QGIS of het beheren van opslagplaatsen, kunt u meer informatie vinden op Get Involved in the QGIS Community.

Documentatie schrijven

Kopregels

Elke webpagina van de documentatie komt overeen met een .rst-bestand.

Secties die worden gebruikt om de tekst te structureren worden geïdentificeerd door middle van hun titel die onderstreept is (en met een streep boven voor het eerste niveau). Titels op hetzelfde niveau moeten hetzelfde teken gebruiken voor eenduidig onderstrepen. In QGIS Documentation zou u de volgende stijlen moeten gebruiken voor hoofdstuk, sectie, subsectie en minisec.

********
Chapter
********

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

Tags in regels

U kunt binnen de tekst enkele tags gebruiken om enkele items te benadrukken.

  • Menu gui: om een volledige reeks menuselecties te markeren, inclusief het selecteren van submenu’s en het kiezen van een specifieke bewerking, of een subreeks van een dergelijke reeks.

    :menuselection:`menu --> submenu`
  • Titel dialoogvenster en tab: Labels weergegeven als deel van een interactieve gebruikersinterface inclusief titel van het venster, titel van de tab en labels voor opties.

    :guilabel:`title`
  • Labels voor knoppen

    **[Apply]**
  • Bestandsnaam of -map

    :file:`README.rst`
  • Pictogram met pop-uptekst behorende tot het pictogram

    |icon| :sup:`popup_text`

    (zie image hieronder).

  • Sneltoets toetsenbord

    :kbd:`ctrl B`

    zal weergeven Ctrl B

  • Gebruikerstekst

    ``label``
    

Label/verwijzing

Verwijzingen worden gebruikt om ankers binnen de tekst te plaatsen. Het helpt u dan om hyperlinks te maken of aan te roepen tussen secties of pagina.

Het voorbeeld hieronder maakt het anker van een sectie (bijv., titel voor label/verwijzing)

.. _my_anchor:

Label/reference
---------------

Gebruik, om de verwijzing op dezelfde pagina aan te roepen,

see my_anchor_ for more information.

wat terug zal geven:

bekijk my_anchor voor meer informatie.

Bekijk hoe het naar de volgende regel/ding zal springen die volgt op het ‘anker’. Normaal gesproken hoeft u voor het declareren van dit label geen apostrof te gebruiken, maar dient u lege regels voor en na het anker te gebruiken.

Een andere manier om naar dezelfde plek te springen vanuit ergens in de documentatie is om de rol :ref: te gebruiken.

see :ref:`my_anchor` for more information.

wat in plaats daarvan het bijschrift zal weergeven (in dit geval de titel van deze sectie!):

bekijk Label/verwijzing voor meer informatie.

Dus verwijzing 1 (my_anchor) en verwijzing 2 (Label/verwijzing). Omdat de verwijzing vaak het volledige bijschrift weergeeft, is er niet echt de noodzaak om het woord sectie te gebruiken. Onthoud dat u ook een aangepast bijschrift kunt gebruiken om de verwijzing te beschrijven

see :ref:`Label and reference <my_anchor>` for more information.

wat teruggeeft:

bekijk Label and reference Vpor meer informatie.

Figuur en afbeelding

Afbeeldingen

gebruik, om een afbeelding in te voegen

.. image:: /static/common/qgislogo.png
   :width: 10 em

wat teruggeeft

../../_images/qgislogo.png

Vervangen

U kunt een afbeelding binnen tekst plaatsen of een alias toevoegen om het overal te kunnen gebruiken. Maak ergens eenvoudigweg een alias om een afbeelding binnen een alinea te gebruiken.

.. |nice_logo| image:: /static/common/qgislogo.png
               :width: 2 em

en het aanroepen in uw alinea:

my paragraph begins here with a nice logo |nice_logo|.

Hier is hoe dit voorbeeld er uit zal zien:

mijn alinea begint hier met een mooi logo nice_logo.

Notitie

Momenteel wordt, om te zorgen voor consistentie en te helpen bij het gebuiken van pictogrammen van QGIS, een lijst met aliassen gebouwd en beschikbaar gemaakt in het hoofdstuk Vervangingen.

Figuur

.. _figure_readme_1:

.. only:: html

   **Figure Readme 1:**

.. figure:: /static/common/qgislogo.png
   :width: 20 em
   :align: center

   A caption: A logo I like

Het resultaat ziet er uit als dit:

Figure Readme 1:

../../_images/qgislogo.png

Een bijschrift: Een logo dat ik leuk vind

Gebruik .. only:: html om het nummer van de afbeelding (Figure Readme 1) alleen in html-bestanden zichtbaar te maken. De scripts zullen een automatisch gegenereerd nummer invoegen vóór het bijschrift van de afbeelding in pdf.

Voeg eenvoudigweg ingesprongen tekst in na een lege regel in het blok figure om een bijschrift te gebruiken (zie My caption).

Verwijzen naar de afbeelding kan worden gedaan met behulp van het label verwijzing zoals dit

(see Figure_Readme_1_).

Het zal het anker Figure_Readme_1 weergeven. U kunt hoofdletters gebruiken als u dat wilt. Het kan worden gebruikt in hetzelfde .rst-document maar niet in andere .rst-documenten.

U kunt rol :ref: niet meer voor de verwijzing gebruiken, omdat in HTML de verwijzing naar het bijschrijft verloren gaat (het verwijst nu naar de plaats vóór Figure Readme 1:

see :ref:`figure_readme_1`, does not work due to the lost reference to
the caption of the figure, this is not a 'bug' but a choice we made!

Tabellen

Een eenvoudige tabel maken

=======  =======  =======
x        y        z
=======  =======  =======
1        2        3
2        4
=======  =======  =======

gebruik een \ gevolgd door een lege spatie om een lege spatie te laten.

U kunt ook meer gecompliceerde tabellen maken door ze te tekenen met behulp van verwijzingen en zo

.. _my_drawn_table_1:

+---------------+--------------------+
| Windows       | Mac OSX            |
+---------------+--------------------+
| |win|         | |osx|              |
+---------------+--------------------+
| and of course not to forget |nix|  |
+------------------------------------+

My drawn table, mind you this is unfortunately not regarded a caption

You can reference to it like this my_drawn_table_1_.

Het resultaat:

Windows Mac OSX
win osx

en natuurlijk, niet te vergeten, nix

Helaas is voor de door mij getekende tabel geen bijschrift toegelaten

U kunt er op deze manier naar verwijzen my_drawn_table_1.

Index

Er bestaan verscheidene tags voor index in RST. Het is noodzakelijk om ze in de normale tekst te integreren om in staat te zijn de index te kunnen vertalen. Gebruik in dat geval deze syntaxis:

QGIS allows to load several :index:`Vector formats` supported by GDAL/OGR ...

Indien de term niet moet worden vertaald, gebruik dan deze syntaxis:

.. index:: WMS, WFS, WCS, CAT, SFS, GML, ...

Voetnoten

Onthoud: Voetnoten worden niet herkend door enige software voor vertalingen en ze worden ook niet juist geconverteerd naar de indeling PDF. Gebruik dus indien mogelijk geen voetnoten binnen enige documentatie.

Dit is voor het maken van een voetnoot

blabla [1]_

Die zal wijzen naar:

[1]

Bijwerken van plug-ins van de bron

Schermafdrukken beheren

Nieuwe schermafdrukken toevoegen

Nu volgen enkele tips voor het maken van nieuwe goed uitziende schermafdrukken. Voor de gebruikershandleiding worden deze dan geplaatst onder: ./resources/en/user_manual/

  • dezelfde omgeving voor alle schermafdrukken (hetzelfde OS, dezelfde decoratie, dezelfde grootte voor lettertype). We hebben Ubuntu met Unity gebruikt en het standaard thema “ambience”. Voor schermafdrukken van het hoofdvenster van QGIS en Printvormgeving hebben we het ingesteld om menu’s weer te geven in het venster (niet standaard in Unity).

  • verklein het venster naar de minimale ruimte die nodig is om de mogelijkheid weer te geven (het gehele scherm nemen voor een klein modaal venster > overkill)

  • hoe minder vervuiling, hoe beter (niet nodig om alle werkbalken te activeren)

  • wijzig de afmetingen niet in een programma voor bewerken van afbeeldingen, de grootte zal in de rst-bestanden worden ingesteld (verkleinen van de dimensies zonder de resolutie juist omhoog te brengen > lelijk)

  • snijd de achtergrond bij

  • Stel de grootte voor de resolutie voor afdrukken in op 135 dpi, bijv. stel in GIMP de afdrukresolutie in (afbeelding > groote afdruk) en sla op. Op deze wijze zullen, indien er geen afmeting wordt ingesteld in de rst-bestanden, afmetingen hun originele grootte hebben in HTML en een goede resolutie voor afdrukken in de PDF. U kunt ImageMagick’s opdracht convert gebruiken om een batch afbeeldingen te verwerken:

convert -units PixelsPerInch input.png -density 135 output.png
  • sla ze op als png (geen jpeg-artifacten)

  • de schermafdruk zou als inhoud moeten tonen wat overeenkomstig wordt beschreven in de tekst

  • er zijn enkele voorbereide projecten voor QGIS, die eerder werden gebruikt om schermafdrukken te maken, beschikbaar in ./qgis-projects. Dit maakt het eenvoudiger om schermafdrukken te reproduceren voor de volgende nieuwe versie van QGIS. Deze projecten gebruiken de QGIS Sample Data (alias Alaska Dataset), die moet worden geplaatst in dezelfde map als de QGIS-Documentation Repository.

  • Gebruik de volgende opdracht om de globale menufunctie in Ubuntu te verwijderen om kleinere schermen voor de toepassing te maken met menu’s:

sudo apt-get autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

Schermafdrukken vertalen

Nu volgen enkele tips voor het maken van schermafdrukken voor uw vertaalde gebruikershandleiding. Deze dienen te worden geplaatst onder ./resources/<vertaling>/user_manual/

  • dezelfde omgeving voor alle schermafdrukken (hetzelfde OS, dezelfde decoratie, dezelfde lettergrootte)

  • Gebruik de projecten voor QGIS die zijn opgenomen in de QGIS-Documentation Repository (in ./qgis_projects ). Deze zijn gebruikt voor het maken van de ‘originele’ schermafdrukken in de handleidingen. De QGIS Sample Data (alias Alaska Dataset) dient te worden geplaatst in dezelfde map als de QGIS-Documentation Repository.

  • dezelfde grootte als de Engelse ‘originele’ schermafdrukken, anders zullen zij vervormen en er lelijk uitzien. Indien u een andere afmeting nodig heeft vanwege langere tekenreeksen in de UI, vergeet dan niet de dimensie te wijzigen in de rst-code van uw taal.

  • verklein het venster naar de minimale ruimte die nodig is om de mogelijkheid weer te geven (het gehele scherm nemen voor een klein model venster > overkill)

  • hoe minder vervuiling, hoe beter (niet nodig om alle werkbalken te activeren)

  • wijzig de afmetingen niet in een programma voor bewerken van afbeeldingen, de grootte zal in de rst-bestanden worden ingesteld (verkleinen van de dimensies zonder de resolutie juist omhoog te brengen > lelijk)

  • snijd de achtergrond bij

  • sla ze op als png (geen jpeg-artifacten)

  • de schermafdruk zou als inhoud moeten tonen wat overeenkomstig wordt beschreven in de tekst

Algoritmen voor Processing documenteren

Neem, bij het schrijven van documentatie voor algoritmen van Processing, de volgende richtlijnen in overweging:

  • overschrijf geen bestaande documentatie bestanden door bestanden uit andere bronnen (bijv. de bron van QGIS of de opslagplaats Processing-Help). Deze bestanden hebben vaak een andere indeling.

  • De hulpteksten voor verwerkingsalgoritmen zijn onderdeel van de QGIS gebruikershandleiding en gebruiken dus dezelfde opmaak als gebruikershandleiding en andere documentatie.

  • Voorkom het gebruik van zinnen als “Dit algoritme doet dit en dat...” als eerste zin in de beschrijving van een algoritme. Probeer meer beeldende zinnen te gebruiken. Neem de beschrijvingen voor de TauDEM of GRASS algoritmen als voorbeeld.

  • voeg indien nodig afbeeldingen toe. Gebruik de indeling PNG en volg de algemene richtlijn voor het maken van documentatie.

  • voeg indien nodig verwijzingen toe naar aanvullende informatie (bijv. publicaties of webpagina’s) aan de sectie “Zie ook”

  • geef duidelijke uitleg over de parameters en de resultaten van algoritmen (ook hier zijn GRASS en TauDEM goede voorbeelden).

  • wijzig geen namen van parameters of resultaten. Indien u type- of spellingsfouten aantrof — rapporteer deze in het foutmeldingensysteem zodat ontwikkelaars deze ook in de code van Processing kunnen aanpassen.

  • geef geen overzicht van beschikbare opties in de beschrijving van het algoritme, beschikbare opties worden al weergegeven in de beschrijving van de parameter.

  • geef geen informatie over de typen geometrie in de beschrijving van algoritme of parameter zonder duidelijke reden. Deze informatie wordt al beschikbaar gemaakt in de beschrijving van de parameter.