From 9fc585fd9103cb917a1153fbc449c1584c029c56 Mon Sep 17 00:00:00 2001
From: wxiaoguang <wxiaoguang@gmail.com>
Date: Fri, 1 Mar 2024 18:16:19 +0800
Subject: [PATCH] Rename Str2html to SanitizeHTML and clarify its behavior
 (#29516)

Str2html was abused a lot. So use a proper name for it: SanitizeHTML

And add some tests to show its behavior.
---
 administration/mail-templates.en-us.md | 10 +++++-----
 administration/mail-templates.zh-cn.md | 22 +++++++++++-----------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/administration/mail-templates.en-us.md b/administration/mail-templates.en-us.md
index b642ff4a..9077f97a 100644
--- a/administration/mail-templates.en-us.md
+++ b/administration/mail-templates.en-us.md
@@ -224,7 +224,7 @@ Please check [Gitea's logs](administration/logging-config.md) for error messages
         {{if not (eq .Body "")}}
             <h3>Message content</h3>
             <hr>
-            {{.Body | Str2html}}
+            {{.Body | SanitizeHTML}}
         {{end}}
     </p>
     <hr>
@@ -260,19 +260,19 @@ The template system contains several functions that can be used to further proce
 the messages. Here's a list of some of them:
 
 | Name             | Parameters  | Available | Usage                                                                       |
-| ---------------- | ----------- | --------- | --------------------------------------------------------------------------- |
+| ---------------- | ----------- | --------- |-----------------------------------------------------------------------------|
 | `AppUrl`         | -           | Any       | Gitea's URL                                                                 |
 | `AppName`        | -           | Any       | Set from `app.ini`, usually "Gitea"                                         |
 | `AppDomain`      | -           | Any       | Gitea's host name                                                           |
 | `EllipsisString` | string, int | Any       | Truncates a string to the specified length; adds ellipsis as needed         |
-| `Str2html`       | string      | Body only | Sanitizes text by removing any HTML tags from it.                           |
+| `SanitizeHTML`   | string      | Body only | Sanitizes text by removing any dangerous HTML tags from it.                 |
 | `SafeHTML`       | string      | Body only | Takes the input as HTML; can be used for `.ReviewComments.RenderedContent`. |
 
 These are _functions_, not metadata, so they have to be used:
 
 ```html
-Like this:         {{Str2html "Escape<my>text"}}
-Or this:           {{"Escape<my>text" | Str2html}}
+Like this:         {{SanitizeHTML "Escape<my>text"}}
+Or this:           {{"Escape<my>text" | SanitizeHTML}}
 Or this:           {{AppUrl}}
 But not like this: {{.AppUrl}}
 ```
diff --git a/administration/mail-templates.zh-cn.md b/administration/mail-templates.zh-cn.md
index fd455ef3..d58f9dc1 100644
--- a/administration/mail-templates.zh-cn.md
+++ b/administration/mail-templates.zh-cn.md
@@ -207,7 +207,7 @@ _主题_ 和 _邮件正文_ 由 [Golang的模板引擎](https://go.dev/pkg/text/
         {{if not (eq .Body "")}}
             <h3>消息内容：</h3>
             <hr>
-            {{.Body | Str2html}}
+            {{.Body | SanitizeHTML}}
         {{end}}
     </p>
     <hr>
@@ -242,20 +242,20 @@ _主题_ 和 _邮件正文_ 由 [Golang的模板引擎](https://go.dev/pkg/text/
 
 模板系统包含一些函数，可用于进一步处理和格式化消息。以下是其中一些函数的列表：
 
-| 函数名              | 参数        | 可用于       | 用法                                                                              |
-|------------------| ----------- | ------------ | --------------------------------------------------------------------------------- |
-| `AppUrl`         | -           | 任何地方     | Gitea 的 URL                                                                     |
-| `AppName`        | -           | 任何地方     | 从 `app.ini` 中设置，通常为 "Gitea"                                               |
-| `AppDomain`      | -           | 任何地方     | Gitea 的主机名                                                                   |
-| `EllipsisString` | string, int | 任何地方     | 将字符串截断为指定长度；根据需要添加省略号                                        |
-| `Str2html`       | string      | 仅正文部分   | 通过删除其中的 HTML 标签对文本进行清理                                              |
-| `SafeHTML`       | string      | 仅正文部分   | 将输入作为 HTML 处理；可用于 `.ReviewComments.RenderedContent` 等字段               |
+| 函数名              | 参数        | 可用于       | 用法                                                      |
+|------------------| ----------- | ------------ |---------------------------------------------------------|
+| `AppUrl`         | -           | 任何地方     | Gitea 的 URL                                             |
+| `AppName`        | -           | 任何地方     | 从 `app.ini` 中设置，通常为 "Gitea"                             |
+| `AppDomain`      | -           | 任何地方     | Gitea 的主机名                                              |
+| `EllipsisString` | string, int | 任何地方     | 将字符串截断为指定长度；根据需要添加省略号                                   |
+| `SanitizeHTML`   | string      | 仅正文部分   | 通过删除其中的危险 HTML 标签对文本进行清理                                |
+| `SafeHTML`       | string      | 仅正文部分   | 将输入作为 HTML 处理；可用于 `.ReviewComments.RenderedContent` 等字段 |
 
 这些都是 _函数_，而不是元数据，因此必须按以下方式使用：
 
 ```html
-像这样使用：         {{Str2html "Escape<my>text"}}
-或者这样使用：       {{"Escape<my>text" | Str2html}}
+像这样使用：         {{SanitizeHTML "Escape<my>text"}}
+或者这样使用：       {{"Escape<my>text" | SanitizeHTML}}
 或者这样使用：       {{AppUrl}}
 但不要像这样使用：   {{.AppUrl}}
 ```