search

redhat-documentation / vale-at-red-hat

Vale config files, styles, and docs to help individuals and teams roll out Vale
https://redhat-documentation.github.io/vale-at-red-hat/
MIT License
37 stars 58 forks source link

vale errors on hostname, TLS, terminal, OS, vscode #145

Closed max-cx closed 2 years ago

max-cx commented 2 years ago

Describe the bug The following words or expressions trigger illegitimate vale alerts:

1. We need hostname as per IMB Style on p. 292: image I suggest downgrading this rule to a warning to avoid massive fixes of host name to older docs and to allow for use of hostname in new docs.

2. The following screenshot is self-explanatory--the lintered text is SSL TLS: image How it happened: At first I had just TLS in the text: this was blocked by Vale as an error. So I changed it to SSL TLS: :smile: now I got two errors, one for SSL (Vale doesn't see TLS with it) and one for TLS (Vale doesn't see SSL with it). In my docs, only TLS is mentioned. If I have to add SSL, that may be technically incorrect: https://www.internetsociety.org/deploy360/tls/basics/ https://www.ssl.com/faqs/faq-what-is-ssl/ I suggest removing this rule also because SSL and TLS don't seem to be the same thing and in many situations only one of them should be mentioned.

3. image The above rule prevents me from using phrases like "in the terminal window". I can live with having to use shell prompt, if I'm forced to do so by Vale, to describe how to enter a command; however, in other situations, like when asking the user to (for example) verify the output of a command in the terminal window, the meaning doesn't work with shell prompt (or even with command line). So based on my experience, shell prompt and terminal are not interchangeable (and by extension also terminal window because then I can't write even terminal window as Vale will block it as an error due to terminal in it). Please also note that IMB Style does not prohibit use of the word terminal, as can be seen on p. 347: image I suggest downgrading this rule to a warning as explained.

4. image As the screenshot above shows, we cannot always replace OS with operating system. There are product names that have OS in them like macOS and z/OS as in :https://www.eclipse.org/che/docs/che-7/extensions/eclipse-che4z/ and in https://github.com/eclipse/che-docs/pull/2204/ I suggest downgrading this rule to a warning as explained.

5. image Lower-case vscode should be acceptable because of its occurrences in third-party links. I suggest downgrading this rule to a warning as explained.

themr0c commented 2 years ago

Thanks for the report! To work on that, we will have to split into 5 distinct issues.

themr0c commented 2 years ago

Please add point 3. to #114.

themr0c commented 2 years ago

For 2., see #147

themr0c commented 2 years ago
  1. is a good candidate for scoping. Disable a rule that is irrelevant in the file context. See https://redhat-documentation.github.io/vale-at-red-hat/docs/end-user-guide/defining-a-vale-onboarding-strategy/#_fix_the_alerts
themr0c commented 2 years ago
  1. is a good candidate for scoping too. Disable a rule that is irrelevant in the file context. See redhat-documentation.github.io/vale-at-red-hat/docs/end-user-guide/defining-a-vale-onboarding-strategy/#_fix_the_alerts
themr0c commented 2 years ago

For 1.: Indeed, SSG removed the entry for "host name". See: https://github.com/redhat-documentation/supplementary-style-guide/pull/114

themr0c commented 2 years ago

1., 2., and 3. are done

  1. and 5. are candidates for exceptional treatment in scoping rules. I believe we are good.
themr0c commented 2 years ago

Implemented with #164