Literal strings in YCP code that contains HTML tags are usually help text that will be displayed in the YaST2 RichText widget. This HTML text is subjected to the sanity checks explained below.
Please notice that everything within double quotes "
will be
checked that contains anything surrounded by angle brackets
<
...>
- i.e. anything that looks remotely like an HTML
tag. Unknown tags will be silently ignored, but the entire text within the
quotes will be checked.
Limitation:
If a portion of help text lacks any HTML tag, it will not be checked since it
will not be recognized by check_ycp
as help text. Such completely
wrong portions of help text will slip through undetected, thus unchecked.
Each HTML text must start with a <p>
tag and end with a
</p>
tag.
There must be a corresponding closing </p>
tag for each opening
<p>
tag.
This is a basic requirement of HTML. The underlying YaST2 widgets may or may not be forgiving enough to tolerate missing tags, but we'd rather not rely on that.
Besides, no other types of paragraphs other than plain text paragraphs
<
p>
... <
/p>
are desired in
YaST2 help texts - in particular, no large font boldface headings etc.
See the intro of this section.
For each portion of HTML text:
<p>
tag is
permitted.</p>
tag is
permitted.</p>
and the next opening
<p>
tag is permitted.
See the intro of this section.
Each single portion of HTML text may contain exactly one paragraph, i.e. one
<
p>
... <
/p>
pair.
This is a convention to make life easier for the translators.
The tools used for extracting translatable texts from the sources (GNU
gettext
) detect differences between the last translated version of a
message and the current message from the latest source. They mark such messages
as fuzzy, i.e. the (human) translator is asked to have a good look at
it and decide whether there has been a real change in the message (thus it
needs to be retranslated) or just a cosmetic change (fixed typo, inserted
whitespace, reformatted the paragraph etc.).
This is a tedious task and it gets more tedious the longer each individual portion of text becomes. Changes from the old to the new version are hard to find if the portions are very long.
Plus, if they are that long it is very likely that always somewhere something has changed, thus the entire text is marked as fuzzy and needs careful manual checking which is not really necessary for all the text.
Split your help texts and use the YCP string addition operator to put them together.
Don't:
help_text = _("<p> bla blurb bla ... blurb bla blurb ... bla blurb bla ... </p> <p> bla blurb bla ... blurb bla blurb ... bla blurb bla ... </p>");
Instead, do:
// Help text (HTML like) help_text = _("<p> bla blurb bla ... blurb bla blurb ... bla blurb bla ... </p>"); // Help text (HTML like), continued help_text = help_text + _("<p> bla blurb bla ... blurb bla blurb ... bla blurb bla ... </p>");
Please also notice the comments for the translators just above the
text. The gettext
tools will automatically extract them along with the
text to translate and put them into the .po
file. The translators can
use them as additional hints what this text is all about.
See the intro of this section.
Such forced line breaks are plain superfluous. The HTML renderer will format the paragraph automatically - after each paragraph there will be a newline and some empty space to set each paragraph apart from the next.
There is no need nor is it desired to add extra empty space between paragraphs. This just looks plain ugly, even more so if this results in different spacings between several paragraphs of the same help text.
The most superfluous of those excess line breaks are those at the very end of a help text - after the last paragraph. Not only are they not good for anything, they sometimes even cause a vertical scroll bar to be displayed even though this would not be necessary otherwise.
Plus, there have been cases where erstwhile last help text paragraphs had been
rearranged so they now are in the middle of the help text - but unfortunately
the trailing <br>
tag had been forgotten and moved along with
the paragraph, thus causing different inter-paragraph spacings.
To make things even worse, fixing this breaks the translation for the affected paragraph: It will be marked as fuzzy just because of this even though it has not really changed.
We cannot entirely get rid of the <br>
tags (but we would like
to). Sometimes they are needed within paragraphs. But at least those
at the end of paragraphs we can do without.