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

[Alvin Wong]

Hi Tyson,

> There are still some unmathced internal links, but they were added to 
> provide additional links to related manual pages which I think should 
> be useful. 
I recommend making merge requests to improve the source too, so all 
languages of the Manual can benefit from it.

> However, there is one particular link type I don't understand: `Word 
> Word Word`_ (not :ref:`name`_). 
The Sphinx documentation has this in 
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref 
:

> Using |ref| 
> <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref> 
> is advised over standard reStructuredText links to sections (like 
> |`Section title`_|) because it works across files, when section 
> headings are changed, will raise warnings if incorrect, and works for 
> all builders that support cross-references.
So I suppose it is a less reliable version of :ref: for same-page 
section linking. It might be a good idea to try replacing them in the 
source with :ref:, but that's for another day...

This markup also seem to have another use, which is separated link 
definition: 
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#external-links

I am not exactly sure how section names references and glossary terms 
are handled with translation. Usually leaving the original in should be 
safe and Sphinx should substitute it with the translated name. I also 
remember once using the translated name in a :term: markup and it still 
worked. I guess in some cases you really have to experiment to see how 
Sphinx like them.

Cheers,

Alvin Wong


Tyson Tan 於 2/1/2022 15:39 寫道:
> Hi Alvin,
>
> Thank you for the information. I've fixed the broken markup errors in 
> zh_CN (yet to be built and sync). There are still some unmathced 
> internal links, but they were added to provide additional links to 
> related manual pages which I think should be useful.
>
> However, there is one particular link type I don't understand: `Word 
> Word Word`_ (not :ref:`name`_).
>
> For example:
>
> Dithering Threshold Modes
> #: ../../reference_manual/filters/map.rst:82
> Is the text of a link.
>
> `Dithering Threshold Modes`_
> #: ../../reference_manual/filters/map.rst:64
> #: ../../reference_manual/filters/map.rst:98
> Creates a link to map.rst:82 with the text of "Dithering Threshold 
> Modes".
>
> Right now I've translated both of them, but I do wonder if I should 
> keep `Dithering Threshold Modes`_ untranslated?
>
> Similarly:
>
> :term:`keyframe`
> #: ../../reference_manual/dockers/animation_curves.rst:56
> This one I left it untouched, because I think it's an assigned name, 
> but I'm not sure.
>
> :ref:`tablet_settings`
> #: ../../KritaFAQ.rst:407
> This one I also left untouched, without a doubt.
>
> Thanks,
> Tyson Tan
>
>  On 2022-01-02 01:17, Alvin Wong wrote:
>> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kimageshop/attachments/20220102/68404736/attachment-0001.htm>