Escape raw rule doc text for HTML

Some the rule config text is intended for use in both tool output and in the reference, so can't be formatted at the
source as the Markdown consumed by the MkDocs website generation system.

This raw text may contain incidental Markdown markup, which would result in it being incorrectly rendered in the
website, so it must be escaped. Despite much searching at the time the rule documentation website generation system was
created, I could not find a good Go package for Markdown escaping of text. I did find an excellent package for Markdown
escaping of HTML, and so I used that instead.

However, this is not sufficient to completely escape the text. The reason is that Markdown is a partial superset of
HTML. The `github.com/JohannesKaufmann/html-to-markdown/escape` package intentionally does not escape HTML. So it is
necessary to do HTML escaping of the raw text in addition to Markdown escaping.

HTML escaping was not done previously, which resulted in raw text which incidentally had the angle bracket enclosed form
of HTML tags not being rendered in the website.

For example, the "brief" text of rule PF009:

```
use of compiler.<pattern type>.extra_flags
```

was rendered as:

```
use of compiler..extra_flags
```

The raw text is now escaped both for HTML and for Markdown during the generation of the rule documentation website
content.

Author: per1234

ruledocsgen/main.go

@@ -55,9 +55,11 @@ func generateRulesDocumentation(ruleConfigurations []ruleconfiguration.Type, out
 	}
 
 	templateFunctions := template.FuncMap{
-		// Some the rule config text is intended for use in both tool output and in the reference, so can't be formatted at
-		// the source as Markdown. Incidental markup characters in that text must be escaped.
-		"escape": escape.MarkdownCharacters,
+		// Some of the rule config text is intended for use in both tool output and in the reference, so can't be formatted
+		// at the source as Markdown. Incidental markup characters in that text must be escaped.
+		"escape": func(rawText string) string {
+			return escape.MarkdownCharacters(template.HTMLEscapeString(rawText))
+		},
 	}
 
 	projectRulesIntroTemplate := template.Must(template.New("messageTemplate").Parse(

ruledocsgen/main_test.go

@@ -108,6 +108,23 @@ func TestAll(t *testing.T) {
 			ErrorModes:       []rulemode.Type{rulemode.Default},
 			RuleFunction:     rulefunction.BoardsTxtMissing,
 		},
+		{
+			ProjectType:      projecttype.Platform,
+			SuperprojectType: projecttype.All,
+			Category:         "configuration files",
+			Subcategory:      "boards.txt",
+			ID:               "PF009",
+			Brief:            "use of compiler.<pattern type>.extra_flags & foo 'bar' \"baz\"",
+			MessageTemplate:  "Board ID(s) {{.}} use compiler.<pattern type>.extra_flags properties. These are intended to be left for use by the user.",
+			Description:      "A board definition in the platform's `boards.txt` configuration file is using one of the `compiler.<pattern type>.extra_flags` properties (e.g., `compiler.cpp.extra_flags`). These are intended to be left for use by the user as a standardized interface for customizing the compilation commands. The platform author can define as many arbitrary properties as they like, so there is no need for them to take the user's properties.",
+			Reference:        "",
+			DisableModes:     nil,
+			EnableModes:      []rulemode.Type{rulemode.Default},
+			InfoModes:        nil,
+			WarningModes:     []rulemode.Type{rulemode.Default},
+			ErrorModes:       []rulemode.Type{rulemode.Strict},
+			RuleFunction:     rulefunction.BoardsTxtUserExtraFlagsUsage,
+		},
 		{
 			ProjectType:      projecttype.PackageIndex,
 			SuperprojectType: projecttype.All,

ruledocsgen/testdata/golden/platform.md

@@ -1,4 +1,4 @@
-Arduino Lint provides 1 rules for the [`platform`](https://arduino.github.io/arduino-cli/latest/platform-specification/) project type:
+Arduino Lint provides 2 rules for the [`platform`](https://arduino.github.io/arduino-cli/latest/platform-specification/) project type:
 
 ---
 
@@ -20,3 +20,24 @@ Subcategory: boards.txt
 | permissive    | ERROR |
 | specification | ERROR |
 | strict        | ERROR |
+
+---
+
+<a id="PF009"></a>
+
+## use of compiler.&lt;pattern type&gt;.extra\_flags &amp; foo &#39;bar&#39; &#34;baz&#34; (`PF009`)
+
+A board definition in the platform's `boards.txt` configuration file is using one of the `compiler.<pattern type>.extra_flags` properties (e.g., `compiler.cpp.extra_flags`). These are intended to be left for use by the user as a standardized interface for customizing the compilation commands. The platform author can define as many arbitrary properties as they like, so there is no need for them to take the user's properties.
+
+
+Enabled for superproject type: all<br />
+Category: configuration files<br />
+Subcategory: boards.txt
+
+##### Rule levels
+
+| `compliance`  |  Level  |
+|---------------|---------|
+| permissive    | WARNING |
+| specification | WARNING |
+| strict        | ERROR   |