Doc: Clarify html escape function description

[tturnerswdev33]

Documentation

The current documentation has this:

html.escape(s, quote=True)
Convert the characters &, < and > in string s to HTML-safe sequences. Use this if you need to display text that might contain such characters in HTML. If the optional flag quote is true, the characters (") and (') are also translated; this helps for inclusion in an HTML attribute value delimited by quotes, as in .

This is somewhat misleading. The function signature shows quote=True is the default.
However the description says that the flag quote is optional but if you set it to true the characters (") and (') are also translated. This implies that you must pass quote=True to get it to translate (") and ('), which is not the case. The default is quote=True so if you pass nothing it will still translate (") and (').

I think the description should be something clearer like:

function:: escape(s, quote=True)

Convert the characters &, < and > in string s to HTML-safe
sequences. Use this if you need to display text that might contain such
characters in HTML. If the optional flag quote is true or if not set at all, the characters
(") and (') are also translated (default behavior); this helps for inclusion in an HTML
attribute value delimited by quotes, as in <a href="...">. If the optional flag quote is false,
the characters (") and (') are not translated.

I think that this came from the history of cgi escape whose default flag was set to false so this function the default was set to true but that is not clear in this description as to how it operates.

Linked PRs

• gh-139006: Doc: Clarify html.escape function description #139016
• [3.14] gh-139006: Doc: Clarify html.escape function description (GH-139016) #139036
• [3.13] gh-139006: Doc: Clarify html.escape function description (GH-139016) #139037

[ezio-melotti]

Fixed! Thanks @tturnerswdev33 for the report and @PrinceNaroliya for the fix.