Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
max-cx opened this issue Jan 5, 2022 · 8 comments
Closed

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

max-cx opened this issue Jan 5, 2022 · 8 comments
Labels
bug Something isn't working

Comments

@max-cx
Copy link

max-cx commented Jan 5, 2022

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: 😄 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 eclipse-che/che-docs#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.

@max-cx max-cx changed the title vale errors on hostname, TLS, terminal vale errors on hostname, TLS, terminal, OS, vscode, / Jan 5, 2022
@max-cx max-cx changed the title vale errors on hostname, TLS, terminal, OS, vscode, / vale errors on hostname, TLS, terminal, OS, vscode Jan 5, 2022
@themr0c
Copy link
Collaborator

themr0c commented Jan 10, 2022

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

@themr0c
Copy link
Collaborator

themr0c commented Jan 10, 2022

Please add point 3. to #114.

@themr0c themr0c added the bug Something isn't working label Jan 10, 2022
@themr0c
Copy link
Collaborator

themr0c commented Jan 10, 2022

For 2., see #147

@themr0c
Copy link
Collaborator

themr0c commented Jan 19, 2022

  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
Copy link
Collaborator

themr0c commented Jan 19, 2022

  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
Copy link
Collaborator

themr0c commented Jan 19, 2022

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

@themr0c
Copy link
Collaborator

themr0c commented Jan 19, 2022

1., 2., and 3. are done
4. and 5. are candidates for exceptional treatment in scoping rules.
I believe we are good.

@max-cx max-cx mentioned this issue Jan 19, 2022
@themr0c
Copy link
Collaborator

themr0c commented Feb 1, 2022

Implemented with #164

@themr0c themr0c closed this as completed Feb 1, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
Status: Done
Development

No branches or pull requests

2 participants