Switch from html to escape in the l() function / link generator

Started to work.

Initial patch.

@dawehner: Thanks. Looks like didn't get the task completely from first time.
New patch.

For test bot.

New patch version.

Possible scope creep, but at some point we should change the "html" property as it is horribly misleading. In know in theory it means "this contains HTML, so trust me, really", but it's completely non-descriptive of what is *actually* implied, which is "don't check-plain me, trust me on the content".

This is totally backwards. html is exactly the right name for the property. escape or sanitize or any variation of it just keeps the confusion between security and encoding.

Because you know, it is *not* about security. It's about two different types of strings:

• Plain-text strings on one side, that have to be encoded to be displayed in an HTML context (but not in a plain-text context like say, a CSV export);
• HTML strings on the other, that can contain HTML markup. Those do not need to be encoded to be displayed in an HTML context but might have to be sanitized. Those cannot be displayed in a plain-text context, other then approximately (which is the role of drupal_html_to_text).

This is confusing the hell out of people (for example [1] and [2]), and we should not promote the confusion. html: true or false makes perfect sense and do precisely what it says.

html may makes perfect sense, but for someone reading the documentation for the first time, escape is clearer because more commonly used. In order to understand the sense of html here you actually have to explain it! While escape means what it means: do or don't fuck up my input string, no matter how. I think that escape with a default to true is actually way clearer for newcommers and people reading the doc. Anyway, the output of the function will always be html and this setting makes no sense at first glance because as a documentation reader, I could question it this way: how do the fuck this function might not return HTML at all?; It's a probable confusion. With escape everything makes it clearer.

@pounard: escape (or the other widely used sanitize) need to explain what they do just the same. Are they transforming plain-text to HTML (what is typically called "escaping") or do they remove harmful bits from HTML (what is typically called "sanitizing")?

Which one of those is correct, and how does that depends on the value of the escape parameter?

• I need to pass plain-text.
• I need to pass HTML.
• I need to pass safe HTML.

If the only problem is that it's unclear that html applies to the input only, let's just rename it to html_text or html_input.

Let's not lose sight that it is about the type of the input, not what the function does with it (and obviously, it would be way easier if we had strong types like PlainTextString and HtmlString, both extending String).