Adding "Symbols" rule

[aireilly]

Based on: https://redhat-documentation.github.io/supplementary-style-guide/#_symbols

[github-actions]

🎊 Navigate the preview: https://redhat-documentation-vale-at-red-hat-413.surge.sh 🎊

[github-actions]

Click here to review and test in web IDE:

[aireilly]

@jhradilek WDYT?

[jhradilek]

Hi @aireilly, I am terribly sorry for my late reply, I did not notice the mention.

This is a great addition and the output is very helpful. I ran this on my large documentation set and the only error I found is that the rule incorrectly reports unset AsciiDoc attributes. You can reproduce it by adding the following in .vale/fixtures/RedHat/Symbols/testvalid.adoc:

:!attribute:
:attribute!:

The only other questionable case is in keyboard macros where I am not sure what is our official guidance for key combinations:

kbd:[Ctrl + a]

[jhradilek]

I spoke too early. Can we please add an exception for C++?

[aireilly]

Excellent feedback @jhradilek I will review and incorporate your suggestions. I need to test against some other repos too I think.

[jhradilek]

I was looking up documentation on the include statement and accidentally found one more problematic case. According to the documentation, prefixing an include statement with a backslash is a valid way to escape it. Consequently, the following is incorrectly reported by Vale:

\include::example.adoc[leveloffset=+1]

I am not aware of situations where we actually use this in our documentation and cannot imagine it is common outside of a verbatim block, but thought I should report it.

[aireilly]

@jhradilek This one is ready for review finally. Note asciidoctor/asciidoctor#1208

C++ is tricky for AsciiDoc processors. There is a builtin {cpp} attribute for this.

[jhradilek]

Hi @aireilly, I just tested it on my production data and noticed that the current version reports + symbols in list continuations and inside code blocks. To reproduce, add the following at the end of .vale/fixtures/RedHat/Symbols/testvalid.adoc:

. Lists and procedure steps can use a list continuation:
+
[literal,subs="+quotes"]
....
$ *diff --unified a b*
--- a  2023-08-22 19:02:22.940992549 +0100
+++ b  2023-08-22 19:03:12.244543569 +0100
-hello
+goodbye
....

Running vale on it produces the following output:

$ vale testvalid.adoc

 testvalid.adoc
 15:1   suggestion  Do not use the '+' symbol.  RedHat.Symbols 
 19:38  suggestion  Do not use the '+' symbol.  RedHat.Symbols 
 20:1   suggestion  Do not use the '+' symbol.  RedHat.Symbols 
 20:2   suggestion  Do not use the '+' symbol.  RedHat.Symbols 
 20:3   suggestion  Do not use the '+' symbol.  RedHat.Symbols 
 20:38  suggestion  Do not use the '+' symbol.  RedHat.Symbols 
 22:1   suggestion  Do not use the '+' symbol.  RedHat.Symbols 

✔ 0 errors, 0 warnings and 7 suggestions in 1 file.

I think most of these could be avoided if you just ignore + symbols at the beginning of a line and their duplicates.

[aireilly]

I might just remove the + checking altogether. It's used quite a bit in AsciiDoc.

[aireilly]

Oh actually if we remove scope:raw those list continuations are ignored. OK, this is working as it should I think. I'll do some more tests against RHEL and OCP to verify.

[jhradilek]

I didn't think about changing the scope, that's a good point. Just please be aware that Vale's understanding of what the sentence scope is differs from what is intuitive. It will for example not report problems in bullet points, try changing the contents of the testinvalid.adoc file as follows:

Don't use this!
Don't use this & that
This + that is not OK.

* `this` is a bullet point. Don't use this!
* Don't use this & that.
* This + that is not OK.

Vale sadly ignores the last three lines:

$ vale testinvalid.adoc 

 testinvalid.adoc
 2:16  suggestion  Do not use the '&' symbol.  RedHat.Symbols 
 3:6   suggestion  Do not use the '+' symbol.  RedHat.Symbols 
 5:43  suggestion  Do not use the '!' symbol.  RedHat.Symbols 

✔ 0 errors, 0 warnings and 3 suggestions in 1 file.

[jhradilek]

Actually, looking at the line numbers again, in addition to what I stated above there seems to be another problem similar to what we observed in PR #366.

[aireilly]

@jhradilek OK, can't spend any more time on this. Vale/AsciiDoc are too finicky around + symbol. I'm dropping it from this PR.

Interesting re:sentence scope. That's quite counterintuitive IMO. I may raise it as a bug on the Vale project.

[jhradilek]

Suggested change

	Do not use symbols such as ampersand (`&`), exclamation point (`!`), or plus symbol (`+`) in original body copy.
	Do not use symbols such as ampersand (`&`) or exclamation point (`!`) in original body copy.

[jhradilek]

Thanks for all your work on this! Looks good to me.