Convencions del marcatge per al Manual del Krita

Aquí es detallen les convencions d'estil per a utilitzar text reestructurat per al Manual del Krita.

Es recomana consultar l'especificació oficial per a «reStructuredText», i atès que es troba a SourceForge, deseu-ne una còpia al vostre disc dur (el SourceForge, en el moment d'escriure això, té alguns problemes amb el temps d'activitat del servidor):

Manual d'usuari:
Documentació de referència:
Documentació específica de Sphinx:

Hi ha diferències entre el «reStructuredText» oficial i les múltiples maneres en la documentació de Sphinx per a fer les coses. Aquest document especifica les convencions aconsellades que cal seguir.

Metadades

Cada pàgina haurà de començar amb les següents tres coses:

  1. Una metadescripció

    Aquesta serà una descripció general de la pàgina. Es convertirà en una metaetiqueta HTML, la qual utilitzaran els motors de cerca:

    .. meta::
        :description:
            Descripció.
    
  2. Una llista dels autors i la llicència

    Simplement només és per a fer un seguiment de qui va editar la pàgina i per a donar crèdit. Haurà d'aparèixer en un comentari de manera que les màquines no puguin llegir-lo amb facilitat. La llicència de tot el manual és GDL 1.3 i també cal esmentar-ho aquí:

    .. metadata-placeholder
    
       :authors: - Autor 1
                 - Autor 2
       :license: GNU free documentation license 1.3 or later.
    
  3. Indexar els termes

    Aquests són termes separats per comes sota els quals la pàgina serà indexada a l'Índex. L'índex generat és força útil tant per al PDF com per a les persones que no tenen la certesa de quin és el nom exacte del terme que estan cercant. Es defineixen de la següent manera:

    .. index:: Paraula clau, Paraula clau amb espais, ! Paraula clau de la definició principal
    
  4. Una etiqueta

    Serveix perquè puguem enllaçar amb facilitat la pàgina utilitzant :ref:`nom_etiqueta`. Intenteu que sigui un nom de variable bonic:

    .. _nom_etiqueta:
    

    Després de l'etiqueta, haureu d'afegir una capçalera, ja que :ref:`nom_etiqueta` farà referència a la capçalera per a completar amb el seu text enllaçat.

Capçaleres

Les capçaleres es realitzaran en el següent ordre:

###########
Part/Secció
###########

Per a les pàgines que tenen un munt de subpàgines.

===========
Capçalera 1
===========

Comenceu així la majoria de les pàgines del manual.

Capçalera 2
-----------

Capçalera 3
~~~~~~~~~~~

Capçalera 4
^^^^^^^^^^^

Capçalera 5
'''''''''''

Capçalera 6
"""""""""""

Aquestes convencions van ser més o menys decidides al mediawiki de Pandoc per a la conversió a «reStructuredText». Si necessiteu més de 4 capçaleres, pregunteu-vos primer si no s'ha complicat la pàgina i necessita dividir-se.

A vegades és necessari enllaçar amb la subsecció d'una pàgina, en aquest cas afegiu una etiqueta per sobre de la capçalera.

Les capçaleres no hauran d'acabar amb puntuació, ja que la capçalera s'utilitzarà com el nom de l'enllaç en vincular amb una etiqueta.

Enllaçar

L'enllaç es realitza amb :ref:`nom_etiqueta`. Quan necessiteu un text alternatiu d'enllaç, utilitzeu :ref:`text real que es mostrarà <nom_etiqueta>`.

Enllaçar amb pàgines externes es realitza amb `url`_ i `nom enllaç <url>`_, els quals es convertiran en el nom de l'enllaç.

A Pandoc li agrada convertir-los en `nom_enllaç`__ i després afegir .. __ :url al final del document. Aquest és l'anomenat «enllaç anònim», vol dir que depenent de l'ordre en què apareixen els enllaços en el text, l'ordre dels enllaços al final del text hi estarà associat. Si això sona confús i difícil, és perquè ho és. Aquesta també és la raó exacta per la qual ens agradaria evitar enllaços com aquests.

Notes a peu de pàgina i lectura addicional

Les notes a peu de pàgina es poden fer de tres maneres, la més comuna és disposar un recompte automàtic, segons la referència:

1 és una referència a la nota a peu de pàgina 1, i 2 és una referència a la nota a peu de pàgina 2.

1

Aquesta és una nota a peu de pàgina 1.

2

Aquesta és una nota a peu de pàgina 2.

3

Aquesta és una nota a peu de pàgina 3.

3 és una referència a la nota a peu de pàgina 3.

Aquesta és una referència de la cita: [CIT2002].

CIT2002

Aquesta és la cita. És com una nota a peu de pàgina, excepte que l'etiqueta és de text.

També s'hi pot fer referència amb `cita <CIT2002>`_.

En realitat, en aquest manual no fem servir les notes a peu de pàgina perquè és una mica massa acadèmic per als nostres lectors. No obstant això, si recollim documents i enllaços al final d'una pàgina que ofereixen una mica més d'informació sobre un tema. L'Sphinx té la directiva .. seealso:: per a enllaçar amb enllaços externs, mentre que «reStructuredText» aconsella utilitzar .. rubic:: Notes al peu de pàgina per a recopilar específicament les notes a peu de pàgina, ja que això es veu bonic amb el LaTeX.

Imatges

Utilitzeu la directiva «image» per a les imatges sense llegenda:

.. image:: /images/sample.png
   :width: 800
   :align: center
   :alt: una imatge.

I la directiva «figure» per a les imatges amb llegenda:

.. figure:: /images/sample.png
   :figwidth: 800
   :align: center
   :alt: una imatge.

   Una llegenda: observeu com la primera lletra de la llegenda s'alinea amb l'opció «:figwidth:».

Aquesta última ens donarà:

an image.

Una llegenda: observeu com la primera lletra de la llegenda s'alinea amb l'opció «:figwidth:».

Les imatges hauran d'anar a la carpeta /images. En emprar /images en lloc de images, l'Sphinx sabrà que el camí del fitxer no és relatiu.

Marcatge al text

Podeu fer que el text estigui emfatitzat i destacat amb un sol asterisc i doble respectivament:

*emfatitzat*
**destacat**

No podreu fer ambdues coses, *emfatitzat i destacat*, així que trieu.

Podeu crear text amb subscript i amb superscript emprant :sub:`text` i :sup:`text`.

No obstant això, utilitzeu-ho amb moderació! En qualsevol cas, es prefereix utilitzar el marcatge semàntic existent a l'Sphinx, perquè aquest facilita que l'equip de traducció prengui decisions sobre la naturalesa del text:

:menuselection:`Settings --> Configure Krita...`
:guilabel:`File`
:kbd:`Ctrl + Z`
:program:`Krita`

Eviteu paraules en negreta a l'atzar. No farà que el text sigui més fàcil de llegir.

Substitució de les referències

Podeu crear una mena de transcripció per a un fragment de text o una imatge fent el següent:

.. |transcripció| replace:: una cosa o l'altra.

El qual vol dir que si empreu |transcripció| en el text, serà substituït per «una cosa o l'altra». És útil per a les imatges i text que necessiteu donar format de manera complicada, com en el cas de LaTeX.

La documentació del Krita té |mouseleft|, |mousemiddle|, |mousescroll| i |mouseright|, els quals es convertiran en mouseleft, mousemiddle, mousescroll i mouseright respectivament. Aquestes estan definides al fitxer «conf.py» de l'Sphinx i s'afegeixen a cada fitxer RST.

Per als enllaços, si reutilitzeu el mateix un cop i un altre, podeu escriure una cosa com la següent al final del fitxer:

.. _Bugzilla: https://bugs.kde.org/
.. _Krita Manual: https://docs.krita.org/

Després, en escriure un enllaç, podreu emprar `Bugzilla`_ per a enllaçar-hi i amb «Bugzilla» com a text de l'enllaç. `Krita Manual`_ al seu torn enllaçarà amb el web docs.krita.org amb el text «Krita Manual».

Llistes

Llistes ordenades

  1. Poma

  2. Pera

  3. Plàtan

O...

  1. Taula

  2. Cadira

  3. Armari

  1. August

  2. Neró

  3. Calígula

  4. Trajà

Es poden definir de la següent manera:

1. Poma
2. Pera
3. Plàtan

#. Poma
#. Pera
#. Plàtan

A. Taula
B. Cadira
C. Armari

A. Taula
#. Cadira
#. Armari

I. August
#. Neró
#. Calígula
#. Trajà

Llistes desordenades

  • vermell

  • groc

  • verd
    • verd marí

    • verdet

    • xarxet

    • viridian

    • maragda
      • maragda fosc

      • maragda clar
        • maragda molt clar

  • blau

Es defineix de la següent manera:

- vermell
- groc
- verd
    - verd marí
    - verdet
    - xarxet
    - viridian
    - maragda
        - maragda fosc
        - maragda clar
            - maragda molt clar
- blau

Llistes de definicions

Un preferit! Les llistes de definicions són especialment útils quan es tracta d'enumerar totes les opcions en un acoblador, per a després intentar afegir una explicació senzilla.

Definició

Explicació.

Una altra opció

Explicació.

Per a crear-les.

Les podeu crear fent el següent:

Definició
    Explicació.
Una altra opció
    Explicació.

Taules

Finalitat

Tipus de taula

Llistar les dreceres

Taula senzilla

Un munt de «colspan»

Taula de quadrícula

Senzill però llarg

Taula de llista

Es fa de la següent manera:

====================== =====================
Finalitat              Tipus de taula
====================== =====================
Llistar les dreceres  Taula senzilla
Un munt de «colspan»  Taula de quadrícula
Senzill però llarg    Taula de llista
================== =========================

+---------------------+---------------------+
|Finalitat             |Tipus de taula       |
+=====================+=====================+
|Llistar les dreceres |Taula senzilla       |
+---------------------+---------------------+
|Un munt de «colspan» |Taula de quadrícula  |
+---------------------+---------------------+
|Senzill però llarg   | Taula de llista     |
+---------------------+---------------------+

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

   - * Finalitat
     * Tipus de taula
   - * Llistar les dreceres
     * Taula senzilla
   - * Un munt de «colspan»
     * Taula de quadrícula
   - * Senzill però llarg
     * Taula de llista

Les taules de quadrícula són les millors per a quan es necessiten totes les característiques, com columnes i files complexes, però són difícils de crear. Per aquesta raó, les taules petites es fan millor amb una sintaxi senzilla, mentre que les taules realment llargues es fan millor amb una directiva de llista perquè és molt més fàcil d'escriure i mantenir.

Amonestacions i apartats

Nota

Les amonestacions són una mena de secció separada a la qual el lector haurà de prestar atenció.

Les amonestacions que es poden utilitzar són les següents (per ordre de serietat):

Suggerència

Els suggeriments són útils per a proporcionar una mica més d'informació sobre un tema que és útil en el text principal. Com ara, «Aquests paquets s'anomenen de diferent manera a openSUSE en comparació amb Debian».

Truc

Informació addicional sobre com fer alguna cosa, com ara, «Podeu crear una plantilla de la configuració del vostre document preferit» o «Utilitzeu m per a emmirallar el llenç i veure els errors al vostre dibuix amb més facilitat».

Important

Alguna cosa que és important tenir en compte, però no que no haurà de ser necessàriament negativa.

Avís

En general, quan alguna cosa és negativa.

Atenció

Captador general de l'atenció. Feu-la servir quan el tema sigui més important que un avís, però no tan important com tenir una pèrdua de les dades.

Compte

És per a coses que poden provocar pèrdua de les dades, com oblidar-vos de desar o que el Python no disposa actualment de la funcionalitat de desfer.

Perill

Hauria de ser per a coses perilloses per a l'ordinador en general, això inclou coses que poden provocar que es congeli l'estil de la memòria.

Error

Probablement aquesta no sigui rellevant per a un manual. L'Sphinx pot crear-les manualment indicant algunes situacions, però la nostra configuració no ho fa de manera predeterminada.

Amonestació genèrica que pot contenir qualsevol text

Text.

El podeu crear fent el següent:

.. admonition:: Amonestació genèrica que pot contenir qualsevol text

    Text.

L'Sphinx també afegeix:

.. seealso::

    És útil per a recopilar enllaços externs i referències.

Regles horitzontals

Els regles horitzontals normalment s'utilitzen quan el tema canvia de forma directa. Això és molt comú en una escriptura més narrativa, com ara història o ficció. El manual del Krita és més un estil d'escriptura amb instruccions i de referència, és a dir, no solem explicar una història llarga per a indicar com es combinen els diferents elements, sinó que hi ha històries llargues per a motivar el fet que es prenguin certs passos d'una determinada manera. Els canvis de tema solen succeir perquè entrem en una secció nova, en lloc de canviar a una secció relacionada. Per tant, és millor utilitzar capçaleres o la directiva .. Topic::. Les capçaleres també faciliten la lectura.


Dit això, els regles horitzontals es poden crear amb ----.

La directiva «rubric»

La directiva «rubric» és una directiva de capçalera que a primera vista sembla un «tema», però quan el tema té diversos paràgrafs, «rubric» només tractarà la capçalera, de la següent manera:

.. rubric:: La directiva «rubric»

Llavors, quan emprar-la?

Utilitzeu-la només si creieu que el tema és massa petit per a tenir una capçalera adequada.

Topic

Quan el text estigui separat del flux principal, es tracta d'un tema diferent.

Rubric

Quan el text no està separat del flux principal, però tampoc necessita una capçalera.

Amonestacions

Només quan encaixen semànticament. Això és especialment necessari per a les amonestacions sobre perill i avís, ja que veure-les amb massa freqüència pot fer que els usuaris no les vegin.

Retalls de codi

Els retalls de codi inclosos es fan amb ``accents oberts``.

Els retalls de codi de múltiples línies es realitzen en finalitzar la secció anterior amb ::, el qual es veurà així:

Aquest és un paràgraf, i definim un retall de codi amb format previ així::

    Assegureu-vos d'afegir un espai en blanc i una tabulació abans de començar el retall.

També podeu utilitzar la directiva .. code::. Si afegiu el nom del llenguatge després d'aquest, es farà el ressaltat de sintaxi apropiat:

.. code:: python

    # comentari a Python
    def my_function():
        alist = []
        alist.append(1)
        string = "hola món"

Esdevindrà

# comentari a Python
def my_function():
    alist = []
    alist.append(1)
    string = "hola món"

alguns més...

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

    // Comprova si hi ha més que 12
    if (i>12) {
        i = 0;
    }
    return i;
}
/* comentari a CSS */
body {
    margin: 0 auto;
    /* 800 encara és sensat? */
    max-width:800px;
    font-size:16px;
    color:#333;
    background-color: #eee;
    padding:1em;
    font-family:serif;
    line-height: 1.4;
}
<p>aquest <span style="font-style:italic">és</span> <!-- un comentari a HTML --> un paràgraf.</p>

Altres textos amb format previ

Es pot
format previ
el text
anteposant
cada línia
amb un caràcter
de barra vertical

D'aquesta manera:

| Es pot donar
| format previ
| al text
| anteposant
| cada línia
| amb un caràcter
| de barra vertical

En general, això no s'utilitza en el manual i només s'hauria d'utilitzar quan sigui absolutament necessari per a representar el contingut que necessita un format exacte, però mai per raons merament estètiques.

Glossaris, termes i índexs

Aquestes són característiques de l'Sphinx.

«index» s'empra a la secció superior, en aquest moment només s'empren entrades «index» úniques.

Els glossaris s'utilitzen per a algunes de les seccions amb entrades del menú, però no per a totes.

Cites de bloc

Les cites de bloc es fan així:

I am not sure why you'd need quotes in a user manual...
(No estic segur de per què necessitaríeu cites de bloc en un manual d'usuari...)

-- Wolthera

Això esdevindrà en una cita de bloc (blockquote).

I am not sure why you'd need quotes in a user manual... (No estic segur de per què necessitaríeu cites de bloc en un manual d'usuari...)

—Wolthera

En realitat utilitzem cites de bloc en alguns llocs. Intenteu afegir un enllaç al nom per a definir d'on ve.

Text només per a traduccions no angleses

Podeu utilitzar el següent per a incloure text que només té sentit per a les traduccions no angleses del manual, per exemple, per a proporcionar als lectors no anglesos els noms en anglès d'un element com a referència:

.. only:: non_english

    Aquest contingut estarà ocult per a la versió en anglès, però és
    traduïble i es mostrarà en les versions que no estiguin en anglès.

Notes per als traductors

Si esteu traduint el manual per a un idioma que generalment no empra espais en blanc al voltant de les paraules (p. ex., el xinès i el japonès), podeu utilitzar un espai en blanc escapat per a separar les marques i les paraules. Això és particularment útil per als enllaços de les pàgines, com aquest:

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

Cal tenir en compte que en traduir des d'un fitxer PO, haureu d'escapar la barra inversa amb una altra barra inversa:

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

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