8. RichText / HTML Sanity Check

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.

8.1. Completeness of <p> / </p> Paragraph Tags

What

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.

Why

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.

How

See the intro of this section.

8.2. Text Before, After, Between Paragraphs

What

For each portion of HTML text:

  • No text before the first <p> tag is permitted.
  • No text after the last </p> tag is permitted.
  • No text between a closing </p> and the next opening <p> tag is permitted.

Why

Each of those cases is a simple yet common HTML syntax error.

How

See the intro of this section.

8.3. No More Than One Paragraph per Message

What

Each single portion of HTML text may contain exactly one paragraph, i.e. one <p> ... </p> pair.

Why

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.

Workaround

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.

How

See the intro of this section.

8.4. Excess Forced Line Breaks <br> after Paragraphs

What

Forced line break tags <br> are discouraged, especially after a paragraph end tag </p>.

Why

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.

How

<br> after </p> (maybe with anything in between) is rejected. All other <br> tags are silently ignored.