Please check build warnings for the Krita Manual (docs.krita.org)

[Alvin Wong]

Hi,

Thanks to all the translators who contributed to the translations of the 
Krita Manual! Here is something to help improve the translations further:

The docs.krita.org build produces warning output when it encounters 
markup issues, sometimes they may be caused by invalid RST markup in 
translations. We have made it so that it is a bit easier now to check 
the warning output for individual language builds. If you manage or 
contribute to the translations for the Krita Manual, please check these 
output messages.

You can check them by visiting 
https://binary-factory.kde.org/job/Website_docs-krita-org/. Under "Last 
Successful Artifacts" (it may be collapsed, press "Expand all" to view), 
you may find files named `warnings-LANG.log`, where LANG is the language 
code of a translation. It contains a list of warnings produced when the 
Manual for the language is being built. Translators can check the 
relevant file to see if any translations are causing these warnings and 
try to fix them.

I understand these warnings can be hard to parse. I'll try to explain 
with two examples here to help understand them:

---

    /home/user/workspace/Website_docs-krita-org/general_concepts/colors.rst:66:<translated>:1:
    WARNING: Inline strong start-string without end-string.

The first part of the message shows a file path and line number. In this 
case it means the warning is related to the text in 
`general_concepts/colors.rst` on line 66. `<translated>:1` means the 
issue is caused by the translated message. The translation can be found 
in `docs-krita-org_general_concepts__colors.po` (notice that 
`docs-krita-org_` is prepended to the path, slashes are replaced by 
three underscores `___`, and the file extension `.rst` is replaced with 
`.po`).

The warning message refers to a mismatched "strong" markup. In RST the 
markup uses double-asterisks `**`.

This is the relevant lines in the PO file:

    #: ../../general_concepts/colors.rst:66
    msgid ""
    "There are other color models, like :ref:`model_lab`, where we look at the"
    "corresponding gray value of a color first, and then try to describe it, not"
    "it terms of hue and saturation, but by how red, green, blue, and yellow it"
    "is. Because our brains cannot really comprehend a color that is both green"
    "and red, or yellow and blue, this makes them good *polar opposites* in a"
    "sliding scale. We call this a **perceptual model**, as it is based on how"
    "*we see color instead of how the color is generated*."
    msgstr ""
    "Il y a d'autres modèles de couleurs, comme :ref:`model_lab`, où nous"
    "regardons tout d'abord, la valeur de gris correspondant à la couleur et"
    "ensuite, nous essayons de la décrire, non pas en termes de teinte et de"
    "saturation mais de combien de rouge, de vert, de bleu, de jaune, elle est"
    "composée. Puisque nos cerveaux ne peuvent pas réellement appréhender une"
    "couleur étant à la fois, vert et rouge ou jeune et bleu, ceci en fait de"
    "bons **opposés polaires* dans une échelle progressive. Ceci est appelé un"
    "*mode perceptuel*, puisqu'il repose sur la façon dont nous voyons les"
    "couleurs plutôt que comment une couleur est produite."

With sharp eyes you may notice the part `**opposés polaires*` opens with 
double-asterisks but closed with a single asterisk, which is the issue 
the warning message is referring to. The fix is to add another asterisk 
next to the closing asterisk.

---

    /home/user/workspace/Website_docs-krita-org/general_concepts/colors/color_managed_workflow.rst:93:
    WARNING: inconsistent term references in translated message.
    original: [':ref:`here <profiling_and_calibration>`'], translated: []

"Inconsistent term references" means the source message has reference 
links to another page or section, but the translated message is missing 
them or is inconsistent with the source.

This is the lines in the PO file:

    #: ../../general_concepts/colors/color_managed_workflow.rst:93
    msgid ""
    "Device spaces are those describing your monitor, and have to be made using a"
    "little device that is called \"colorimeter\". This device, in combination"
    "with the right software, measures the strongest red, green and blue your"
    "screen can produce, as well as the white, black and gray it produces. Using"
    "these and several other measurements it creates an ICC profile unique to"
    "your screen. You set these in Krita's color management tab. By default we"
    "assume sRGB for screens, but it's very likely that your screen isn't exactly"
    "fitting sRGB, especially if you have a high quality screen, where it may be"
    "a bigger space instead. Device spaces are also why you should first consult"
    "with your printer what profile they expect. Many printing houses have their"
    "own device profiles for their printers, or may prefer doing color conversion"
    "themselves. You can read more about colorimeter usage :ref:`here"
    "<profiling_and_calibration>`."
    msgstr ""
    "Les espaces de périphériques sont ceux décrivant votre écran. Ils doivent"
    "être réalisés à l'aide d'un petit appareil appelé « colorimètre ». Cet"
    "appareil, associé au logiciel adéquat, mesure le rouge, le vert et le bleu"
    "les plus intenses que votre écran peut produire, ainsi que le blanc, le noir"
    "et le gris qu'il produit. À partir de ces mesures et de plusieurs autres, il"
    "crée un profil « ICC » spécifique à votre écran. Vous les définissez dans"
    "l'onglet de gestion des couleurs de Krita. Par défaut, nous supposons"
    "« sRGB » pour les écrans. Mais, il est très probable que votre écran ne"
    "corresponde pas exactement à « sRGB », surtout si vous avez un écran de"
    "haute qualité, qui peut posséder un espace plus grand. Les espaces de"
    "périphériques sont également la raison pour laquelle vous devez d'abord"
    "consulter votre imprimeur pour savoir quel profil il attend. De nombreuses"
    "imprimeries possèdent leurs propres profils de périphériques pour leurs"
    "imprimantes ou préfèrent effectuer elles-mêmes la conversion des couleurs."
    "Vous pouvez en savoir plus sur l'utilisation du colorimètre :ref : « ici"
    "<profilage_et_calibrage> »."

As you can see, the English source message has the reference markup 
":ref:`here <profiling_and_calibration>`", which was mangled in the 
translated message ":ref : « ici <profilage_et_calibrage> »". The 
correct markup can be ":ref:`« ici » <profilage_et_calibrage>`" or "« 
:ref:`ici <profilage_et_calibrage>` »" depending on the wanted outcome. 
Note the backticks and the positioning of whitespaces.

---

Here are some info on RST markup: 
https://docs.krita.org/en/contributors_manual/krita_manual_conventions.html

If you need any help with fixing these errors, please don't hesitate to 
write to the mailing list, or ask in our chat, #krita on Libera.Chat or 
https://webchat.kde.org/#/room/#krita:kde.org with Matrix.

Thanks again for the hard work translating the Krita Manual! :)

Best Regards,

Alvin Wong