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:

Pàgina de Sphinx sobre text reestructurat: és útil per a les directives específiques de Sphinx i les regles que utilitza per a generar, p. ex., el contingut d'una taula.

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:

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ó.
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.
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 manera següent:
.. index:: Paraula clau, Paraula clau amb espais, ! Paraula clau de la definició principal
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.

[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à:

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.

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 ¶

Poma
Pera
Plàtan

O...

Taula
Cadira
Armari

August
Neró
Calígula
Trajà

Es poden definir de la manera següent:

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 manera següent:

- 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 manera següent:

====================== =====================
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.

Advertències i apartats ¶

Nota

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

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

Suggeriment

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 és rellevant per a un manual. L'Sphinx pot crear-les manualment indicant algunes situacions, però la nostra configuració no ho fa de manera predeterminada.

Advertència genèrica que pot contenir qualsevol text

Text.

El podeu crear fent el següent:

.. admonition:: Advertència genèrica que pot contenir qualsevol text

    Text.

L'Sphinx també afegeix:

.. seealso::

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

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 manera següent:

.. 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.
Advertències: Només quan encaixen semànticament. Això és especialment necessari per a les advertències 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 "床前明月光".