Mark-up conventies voor de Krita handleiding ¶

Dit beschrijft op welke manier u de tekst moet markeren om gestructureerde tekst aan te maken in de Krita handleiding.

Het wordt aanbevolen om de officiële specificatie voor reStructuredText te bestuderen, omdat het leeft op sourceforge, een kopie op uw harde schijf op te slaan (sourceforge heeft, op het moment dat dit werd geschreven, problemen met de server uptime):

Gebruikershandleiding:

Referentie documentatie:

Sphinx specifieke documentaties:

Sphinx’ pagina over restructured tekst – Deze is handig voor de specifieke sphinx instructies en functies die het toepast voor het genereren van bijvoorbeeld een tabel met een inhoudsopgave.

Er zijn verschillen tussen de officiële reStructuredText en de documentatie van sphinx over verschillende manieren om iets te doen. Dit document beschrijft de voorgestelde afspraken om iets te doen.

Metagegevens ¶

Elke pagina zou met de volgende drie dingen moeten starten:

Een meta omschrijving
Dit is een algemene omschrijving van de pagina. Het wordt geconverteerd naar een html meta tag wat door zoekmachines zal worden gebruikt:
.. meta:: :description: Omschrijving.
Een lijst met de auteurs en een licentie.
Dit is alleen maar om overzicht te houden over wie de pagina bewerkte en om krediet te geven. Het moet als een commentaar worden geplaatst zodat het niet makkelijk door machines leesbaar is. De licentie van de hele handleiding is GDL 1.3 en moet ook gemeld worden:
.. metadata-placeholder :authors: - Auteur 1 - Auteur 2 :license: GNU free documentation license 1.3 or later.
Termen voor indexatie.
Dit zijn door komma’s gescheiden termen waarmee de pagina zal worden geïndexeerd in Index. De gegenereerde index is erg handig voor zowel PDF als ook voor mensen die niet zeker zijn wat de exacte spelling van de term is waarnaar ze op zoek zijn. Ze zijn als volgt gedefinieerd:
.. index:: Keyword, trefwoord met spaties, ! Belangrijkste definitie van het trefwoord
Een label.
Dit is om makkelijk een link te maken naar een pagina door :ref:`label_name` te gebruiken. Probeer het een goede variabelenaam te geven:
.. _label_name:
Na de label moet u een hoofdstuktitel toevoegen, omdat :ref:`label_name` dan naar het hoofdstuktitel zal refereren als zijn link-tekst.

Hoofdstuktitels ¶

Hoofdstuktitels moeten in de volgende volgorde:

############
Part/Section
############

Voor pagina's die veel subpagina's hebben.

=========
Heading 1
=========

Start hiermee de meeste pagina's van een handleiding.

Heading 2
---------

Heading 3
~~~~~~~~~

Heading 4
^^^^^^^^^

Heading 5
'''''''''

Heading 6
"""""""""

Deze afspraken zijn min of meer besloten door Pandoc’s mediawiki naar reStructuredText conversie. Als u meer dan 4 niveaus in de tekstindeling nodig heeft, vraag dan u zelf af of de pagina niet te ingewikkeld is geworden en opgesplitst moet worden.

Soms moet u een link maken naar een subsectie van een pagina, voeg in dat geval dan een label toe boven het hoofdstuktitel.

Hoofdstuktitels mogen niet eindigen met een punt, omdat de hoofdstuktitel als link wordt gebruikt bij het linken naar een label.

Linken ¶

Linken doet u met :ref:`label_name`. Als u een alternatieve tekst voor de link nodig heeft, dan gebruikt u :ref:`getoonde tekst <label_name>`.

Linken naar externe pagina’s doet u met `url`_ en `link name <url>`_, wat wordt link name.

Pandoc converteert deze graag naar `link name`__ en voegt dan .. __ :url aan het eind van het document toe. Dit is een zogeheten ‘anonymous hyperlink’, wat inhoud dat afhankelijk van de volgorde waarin de links in de tekst verschijnen de volgorde is waarmee de links aan het eind van de tekst een relatie met elkaar hebben. Als dat verwarrend en ingewikkeld klinkt, dan is dat zo omdat het zo is. Dat is precies de reden waarom we proberen om dergelijke links te vermijden.

Voetnoten en verdere leesstof ¶

Voetnoten kunt u op 3 manieren maken, de meest gebruikte is met autonummering, als per referentie:

[1] is een referentie naar voetnoot 1, en [2] is een referentie naar voetnoot 2.

[3] is een referentie naar voetnoot 3.

Hier is een referentie naar een citaat: [CIT2002] .

[CIT2002]

Dit is het citaat. Het is hetzelfde als een voetnoot, behalve dat de label tekstueel is.

U kunt ook een referentie naar een citaat maken met `citation <CIT2002>`_.

Eigenlijk willen we geen voetnoten in de handleiding gebruiken omdat het een beetje te academisch is voor onze lezers. Maar, we verzamelen aan het eind van de pagina wel documenten en links die een beetje extra informatie geven over een onderwerp. Sphinx heeft de .. seealso:: instructie voor externe links, terwijl reStructuredText de suggestie geeft om .. rubic:: Footnotes te gebruiken voor het verzamelen van voetnoten omdat het goed samengaat met LaTeX.

Afbeeldingen ¶

Gebruik de image instructie voor afbeeldingen zonder onderschrift:

.. image:: /images/sample.png
   :width: 800
   :align: center
   :alt: een afbeelding.

En figure instructie voor afbeeldingen met onderschrift:

.. figure:: /images/sample.png
   :figwidth: 800
   :align: center
   :alt: een afbeelding.

   Een onderschrift --  merk op hoe de eerste letter uitgelijnd met de :figwidth: optie.

Dit laatste geeft:

Een onderschrift – merk op hoe de eerste letter uitgelijnd met de :figwidth: optie.¶

Afbeeldingen moeten in de map /images gaan. Door /images in plaats van images te gebruiken, zal sphinx weten dat het pad naar het bestand niet relatief is.

In-tekst Opmaak ¶

U kunt met respectievelijk een enkele asterisk en een dubbele asterisk de tekst nadrukkelijk en sterk maken:

*nadrukkelijk*
**sterk**

U kunt niet zowel *nadrukkelijk als sterk* selecteren, maak dus een keuze.

U kunt _{subscript tekst} en ^{superscript tekst} door :sub:`tekst` en :sup:`tekst` te gebruiken.

Maar, gebruik dit super weinig! het advies is om de bestaande opmaak mogelijkheden van sphinx zoveel mogelijk te gebruiken, omdat dit het leven van de vertalers makkelijker maakt zodat ze beter weten waar de tekst over gaat:

:menuselection:`Instellingen --> Krita configureren...`
:guilabel:`Bestand`
:kbd:`Ctrl + Z`
:program:`Krita`

Vermijd willekeurige vette woorden. Het maak de tekst niet makkelijker leesbaar.

Vervangende referenties ¶

U kunt een soort van afkorting creëren voor een stuk tekst of een afbeelding door het volgende:

.. |shorthand| replace:: het een of ander.

wat inhoud dat als u |shorthand| in de tekst gebruikt, dan zal het worden vervangen door ‘het een of ander’. Dit is handig bij afbeeldingen en tekst dat op een gecompliceerde manier moet worden opgemaakt, zoals in het geval bij “LaTeX”.

Bij links, als u dezelfde link keer op keer gebruikt, dan kunt u zoiets als het volgende schrijven aan het eind van het bestand:

.. _bugzilla: https://bugs.kde.org/
.. _Krita Handleiding: https://docs.krita.org/

Daarna hoeft u bij het typen van een link alleen maar `bugzilla`_ te gebruiken om een link naar bugzilla te maken met “bugzilla” in de tekst gebruikt als tekst van de link. `Krita Handleiding`_ zal wijzigen in een link naar docs.krita.org met de tekst “Krita Handleiding”.

Lijsten ¶

Gewone lijsten ¶

Appel
Peer
Banaan

Of…

Tafel
Stoel
Kledingkast

Augustus
Nero
Caligula
Trajan

Ze kunnen als volgt worden gedefinieerd:

1. Appel
2. Peer
3. Banaan

#. Appel
#. Peer
#. Banaan

A. Tafel
B. Stoel
C. Kledingkast

A. Tafel
#. Stoel
#. Kledingkast

I. Augustus
#. Nero
#. Caligula
#. Trajan

Ongeordende lijst ¶

rood
geel
groen
- zeegroen
- verdigris
- teal
- viridian
- smaragdgroen
  
  donker smaragdgroen
  
  licht smaragdgroen
  
  zeer licht smaragdgroen
blauw

Als volgt gedefinieerd:

- rood
- geel
- groen
    - zeegroen
    - verdigris
    - teal
    - viridian
    - smaragdgroen
        - donker smaragdgroen
        - licht smaragdgroen
            - zeer licht smaragdgroen.
- blauw

Definitie lijsten ¶

Een favoriet! Definitie lijsten zijn met name handig bij het opnoemen van alle opties in een paneel met een korte uitleg daarachter.

Definitie

Uitleg.

Andere optie

Uitleg.

Hoe u ze maakt

U kunt ze als volgt maken:

Definitie
    Uitleg.
Andere optie
    Uitleg.

Tabellen ¶

Doel	Type tabel
lijst met afkortingen	Simple table
Veel vak-samenvoegingen	Grid table
Eenvoudig maar lang	List Table

Doet u als volgt:

================== ============
Doel            Type tabel
================== ============
lijst met afkortingen  Eenvoudige tabel
Veel vak-samenvoegingen   Rooster tabel
Eenvoudig maar lang    Lijst tabel
================== ============

+-----------------+------------+
|Doel          |Type tabel  |
+=================+============+
|lijst met afkortingen|Simple table|
+-----------------+------------+
|Veel vak-samenvoegingen |Grid table  |
+-----------------+------------+
|Eenvoudig maar lang  |List table  |
+-----------------+------------+

.. list-table::
   :header-rows: 1

   - * Doel
     * Type Table
   - * lijst met afkortingen
     * simple table
   - * Veel vak-samenvoegingen
     * grid table
   - * Eenvoudig maar lang
     * list table

U kunt het beste volledige rooster (grid) tabellen gebruiken als u alle functionaliteiten nodig heeft bij bijvoorbeeld complexe samenvoegingen over meerdere kolommen en rijen, maar ze zijn wel moeilijk om te maken. Vanwege deze reden, kunt u het beste eenvoudige tabellen met de simple syntax maken, terwijl u beter de echt lange tabellen met de list instructie kunt maken omdat die veel makkelijker te schrijven en te onderhouden is.

Waarschuwingen en terzijdes ¶

Notitie

Waarschuwingen zijn een min of meer aparte categorie waar de lezer aandacht aan moet geven.

Waarschuwingen die u kunt gebruiken zijn de volgende (in volgorde van serieusheid):

Hint

Hints zijn handig om een beetje meer informatie over een onderwerp te geven dan het handig is in de hoofdtekst. Zoals, “De namen van deze pakketten verschillen in openSuse van Debian”.

Tip

Extra informatie over hoe u iets doet, zoals, “U kunt een sjabloon maken van de instellingen in uw favoriete document”, of “Gebruik m om het werkveld te spiegelen en de fouten in uw tekening makkelijker te herkennen”.

Belangrijk

Iets dat belangrijk is om op te merken, maar niet noodzakelijk negatief.

Waarschuwing

Dit is in het algemeen wanneer iets negatief is.

Let op

Vraagt om algemene aandacht. Gebruik dit wanneer het onderwerp belangrijker is dan een waarschuwing, maar niet zo belangrijk dat het verlies van data veroorzaakt.

Pas op

Dit is voor dingen die verlies van data kunnen veroorzaken, zoals vergeten op te slaan, of dat Python op dit moment niet ongedaan kan maken.

Gevaar

Dit is voor dingen die gevaarlijk voor de computer in het algemeen zijn, dat is inclusief dingen die de computer bevriezen vanwege out of memory.

Fout

Deze is waarschijnlijk niet relevant voor een handleiding. Sphinx kan in sommige situaties deze handmatig creëren, maar onze configuratie doet dat standaard niet.

Algemene waarschuwing dat elke tekst kan hebben

Tekst.

U kunt dit als volgt doen:

.. admonition:: Algemene waarschuwing dat elke tekst kan hebben

    Tekst.

Sphinx voegt ook toe:

.. seealso::

    Wat handig is voor het verzamelen van externe links en referenties.

Dit gezegd hebbende, horizontale linialen kunt u maken met ----.

De rubric instructie

De rubric instructie is een heading instructie die op het eerste gezicht op “topic” lijkt, maar waar de topic over meerdere paragrafen gaat, handelt rubric alleen met het hoofdstuktitel, op deze manier:

.. rubric:: De rubric instructie

Maar, waar gebruikt u deze?

Gebruik het alleen als u denkt dat het onderwerp te onbelangrijk is om een echte hoofdstuktitel te hebben.

Topic: Als de tekst apart is van de stroom, dus het gaat over een ander onderwerp dan de tekst zelf dan is dit de beste keus.
Rubric: Als de tekst niet apart is van de hoofdtekst, maar het hoeft ook geen eigen hoofdstuktitel.
Waarschuwingen: Alleen wanneer ze van toepassing zijn. Dit is met name noodzakelijk voor de waarschuwingen voor gevaar, omdat als ze te vaak worden gebruikt de gebruikers ze gaan negeren.

Code snippers ¶

Inline code snippers doet u met ``backticks``.

Meerregelige code snippers doet u door de vorige sectie te laten eindigen met ::, zodat het als volgt uitziet:

Dit is een paragraaf, en we definiëren een voorgeformateerde snipper als volgt::

    Zorg er voor dat er voor de snipper een spatie en erachter een tab staat.

U kunt ook de instructie .. code:: gebruiken. Als u de naam van de programmeertaal erachter plaatst, dan krijgt u de juiste syntax markering:

.. code:: python

    # Python comment
    def my_function():
        alist = []
        alist.append(1)
        string = "hallo wereld"

Wordt

# Python comment
def my_function():
    alist = []
    alist.append(1)
    string = "hallo wereld"

Nog enige…

// C++ comment
int myFunction(int i) {
    i += 1;

    // Controleer voor meer dan 12
    if (i>12) {
        i = 0;
    }
    return i;
}

/* CSS comment */
body {
    margin: 0 auto;
    /* is 800 nog steeds verstandig? */
    max-width:800px;
    font-size:16px;
    color:#333;
    background-color: #eee;
    padding:1em;
    font-family:serif;
    line-height: 1.4;
}

<p>dit <span style="font-style:italic">is</span> <!-- a HTML comment --> een paragraaf.</p>

Nog meer opgemaakte tekst ¶

Men kan
tekst
vooropmaken
door het vooraf te laten gaan
op elke regel
met een pipe
symbool

Zoals dit:

| Men kan
| tekst
| vooropmaken
| door het vooraf te laten gaan
| op elke regel
| met een pipe
| symbool

Dit wordt in het algemeen niet in de handleiding gebruikt en zou alleen gebruikt moeten worden waar het absoluut vereist is om inhoud te representeren die exact geformatteerd moet zijn, maar nooit alleen voor esthetische redenen.

Woordenlijsten, Termen and Index ¶

Dit zijn functionaliteiten van sphinx

Een index plaatst u in de top sectie, op dit moment worden alleen enkele index lijsten gebruikt.

Woordenlijsten worden voor enkele van de menu item secties gebruikt, maar niet allemaal.

Citaten ¶

Citaten voert u als volgt uit

Ik ben er niet zeker van waarom u citaten nodig hebt in een handleiding...

-- Wolthera

Dit wordt een blokcitaat.

Ik ben er niet zeker van waarom u citaten nodig hebt in een handleiding…

—Wolthera

We gebruiken op enkele plaatsen citaten. Probeer om aan de naam een link te plaatsen naar waar het vandaan komt.

Alleen tekst voor niet-Engelse vertalingen ¶

U kunt het volgende gebruiken voor tekst dat alleen zinvol is voor niet-Engelse vertalingen van de handleiding, om bijvoorbeeld niet-Engelse lezers als referentie de Engelse naam van een item te geven.

.. only:: non_english

    Deze inhoud is verborgen voor de Engelse versie, maar vertaalbaar en
    zichtbaar voor de niet-Engelse versies.

Notities voor vertalers ¶

Als u de handleiding vertaalt voor een taal die gewoonlijk geen witruimte rond woorden gebruikt (bijv. Chinees en Japans), dan kunt u een escaped witruimte gebruiken om opmaak en woorden te scheiden. Dit is speciaal nuttig voor paginakoppelingen, zoals deze:

床前\ `明月 <https://krita.org/>`_\ 光

Merk op dat als u vanaf een PO-bestand vertaalt, u de backslash vooraf moeten laten gaan door een andere backslash:

床前\\ `明月 <https://krita.org/>`_\\ 光

The above produces “床前明月光”, instead of “床前明月光”.