Merge pull request #326 from per1234/html-escape-ruledocs

Escape raw rule documentation text for HTML

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   |