-
Notifications
You must be signed in to change notification settings - Fork 61
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added editorial style guide checking. (#620)
* Added editorial style guide checking. Signed-off-by: dblock <[email protected]> Signed-off-by: Theo N. Truong <[email protected]> Co-authored-by: Theo N. Truong <[email protected]>
- Loading branch information
Showing
61 changed files
with
1,125 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| extends: conditional | ||
| message: "'%s': Spell out acronyms the first time that you use them on a page and follow them with the acronym in parentheses. Subsequently, use the acronym alone." | ||
| link: 'https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md#acronyms' | ||
| level: warning | ||
| scope: summary | ||
| ignorecase: false | ||
| # Ensures that the existence of 'first' implies the existence of 'second'. | ||
| first: '\b((?<!k-)[A-Z]{1,3}\/?[A-Z]{1,3}\d{0,2}\b(?!\sCommons))' | ||
| second: '(?:\b[A-Za-z-]+ )+\(([A-Z]{1,3}\/?[A-Z]{1,3}\d{0,2})\)' | ||
| # ... with the exception of these: | ||
| exceptions: | ||
| - AND | ||
| - API | ||
| - ASCII | ||
| - AWS | ||
| - BASIC | ||
| - BM25 | ||
| - BY | ||
| - CAT | ||
| - CPU | ||
| - CRUD | ||
| - CSV | ||
| - DELETE | ||
| - DNS | ||
| - DOS | ||
| - FAQ | ||
| - FTP | ||
| - GB | ||
| - GET | ||
| - GIF | ||
| - GROUP | ||
| - HAVING | ||
| - HTML | ||
| - HTTP | ||
| - HTTPS | ||
| - I/O | ||
| - ID | ||
| - IP | ||
| - JPEG | ||
| - JSON | ||
| - JVM | ||
| - KB | ||
| - MB | ||
| - N/A | ||
| - NAT | ||
| - NGINX | ||
| - 'NULL' | ||
| - OR | ||
| - PB | ||
| - PNG | ||
| - POST | ||
| - PUT | ||
| - RAM | ||
| - REST | ||
| - RGB | ||
| - ROM | ||
| - SAML | ||
| - SDK | ||
| - SELECT | ||
| - SQL | ||
| - SSL | ||
| - TB | ||
| - TCP | ||
| - TIFF | ||
| - TLS | ||
| - TOC | ||
| - UI | ||
| - URI | ||
| - URL | ||
| - US | ||
| - UTC | ||
| - UTF | ||
| - XML | ||
| - YAML |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| extends: existence | ||
| message: "Don't use an ampersand in place of 'and' in documentation." | ||
| nonword: true | ||
| level: warning | ||
| tokens: | ||
| - '\w +& +\w' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| extends: existence | ||
| message: "Use 'cyber' as a prefix. Remove spaces or hyphens in '%s'." | ||
| level: error | ||
| tokens: | ||
| - '[Cc]yber[- ]+[a-z]*' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| extends: existence | ||
| message: "There should be no spaces around the dash in '%s'." | ||
| ignorecase: true | ||
| nonword: true | ||
| level: error | ||
| scope: | ||
| - ~list | ||
| tokens: | ||
| - '\w+ +-{2,3} +\w+' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| extends: substitution | ||
| message: "Use '%s' instead of '%s' for versions or orientation within a document. Use 'above' and 'below' only for physical space or screen descriptions." | ||
| link: 'https://github.com/opensearch-project/documentation-website/blob/main/TERMS.md' | ||
| level: warning | ||
| ignorecase: true | ||
| swap: | ||
| - image below: following image | ||
| - example below: following example | ||
| - steps below: following steps | ||
| - section below: following section | ||
| - table below: following table | ||
| - image above: following image | ||
| - example above: preceding example | ||
| - section above: preceding section | ||
| - table above: preceding table | ||
| - above image: preceding image | ||
| - above section: preceding section | ||
| - above table: preceding table | ||
| - '\d+\.\d+\s+(?:and|or)\s+above': later | ||
| - '\d+\.\d+\s+(?:and|or)\s+below': earlier | ||
| - 'below(?!\s+(?:the|this|\d))': following or later | ||
| - 'above(?!\s+(?:the|this|\d))': 'previous, preceding, or earlier' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| extends: substitution | ||
| message: "Use '%s' instead of '%s' for window, page, or pane references to features or controls. Use 'top' and 'bottom' only as a general screen reference." | ||
| link: 'https://github.com/opensearch-project/documentation-website/blob/main/TERMS.md' | ||
| level: warning | ||
| ignorecase: true | ||
| action: | ||
| name: replace | ||
| swap: | ||
| - top left: upper left | ||
| - bottom left: lower left | ||
| - top right: upper right | ||
| - bottom right: lower right | ||
| - top-left: upper-left | ||
| - bottom-left: lower-left | ||
| - top-right: upper-right | ||
| - bottom-right: lower-right |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| extends: existence | ||
| message: "Don't use exclamation points in documentation." | ||
| nonword: true | ||
| level: error | ||
| tokens: | ||
| - '\w+!(?:\s|$)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: sequence | ||
| message: "Use 'failover' as an adjective or noun instead of '%s'." | ||
| level: error | ||
| ignorecase: true | ||
| tokens: | ||
| - tag: NN|JJ | ||
| pattern: '(?:fail over|fail-over)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: sequence | ||
| message: "Use 'fail over' as a verb instead of '%s'." | ||
| level: error | ||
| ignorecase: true | ||
| tokens: | ||
| - tag: VB|VBD|VBG|VBN|VBP|VBZ | ||
| pattern: '(?:failover|fail-over)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: existence | ||
| message: "'%s' is in future tense. Use present tense in documentation." | ||
| ignorecase: true | ||
| level: suggestion | ||
| scope: raw | ||
| tokens: | ||
| - '(?:will|is going to|won''t|[A-za-z]+''ll)\s+[a-z]+' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| extends: substitution | ||
| message: "Use '%s' instead of '%s' because the latter is an offensive term." | ||
| link: https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md#offensive-terms | ||
| ignorecase: true | ||
| level: error | ||
| swap: | ||
| abort: stop, end, or cancel | ||
| black day: blocked day | ||
| blacklist: deny list | ||
| kill: stop, end, clear, remove, or cancel | ||
| master account: management account | ||
| master: cluster manager | ||
| slave: replica, secondary, standby | ||
| white day: open day | ||
| whitelist: allow list |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| extends: existence | ||
| message: "Using '%s' is unnecessary. Remove." | ||
| link: https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md#basic-guidelines | ||
| ignorecase: true | ||
| nonword: true | ||
| level: warning | ||
| action: | ||
| name: remove | ||
| tokens: | ||
| - '\b(?:etc\.|etc)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| extends: substitution | ||
| message: "Use '%s' instead of '%s'." | ||
| link: https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md#basic-guidelines | ||
| ignorecase: false | ||
| level: warning | ||
| nonword: true | ||
| action: | ||
| name: replace | ||
| swap: | ||
| '\b(?:eg|e\.g\.)[\s,]': for example or such as | ||
| '\b(?:ie|i\.e\.)[\s,]': that is or specifically | ||
| '\bad hoc[\s,.]': one-time | ||
| '\b(?:v\.|vs\.|vs|versus)\s': compared to or compared with | ||
| '\bvia\s': using, through, by accessing, or by choosing | ||
| '\bvice versa': the other way around |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: sequence | ||
| message: "Use 'login' as an adjective or noun instead of '%s'." | ||
| level: error | ||
| ignorecase: true | ||
| tokens: | ||
| - tag: NN|JJ | ||
| pattern: '(?:log in|log-in)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: sequence | ||
| message: "Use 'log in' as a verb instead of '%s'." | ||
| level: error | ||
| ignorecase: true | ||
| tokens: | ||
| - tag: VB|VBD|VBG|VBN|VBP|VBZ | ||
| pattern: '(?:login|log into|log on|log onto)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: sequence | ||
| message: "Use 'logout' as an adjective or noun instead of '%s'." | ||
| level: error | ||
| ignorecase: true | ||
| tokens: | ||
| - tag: NN|JJ | ||
| pattern: '(?:log out)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: sequence | ||
| message: "Use 'log out' as a verb instead of '%s'." | ||
| level: error | ||
| ignorecase: true | ||
| tokens: | ||
| - tag: VB|VBD|VBG|VBN|VBP|VBZ | ||
| pattern: '(?:logout)' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: existence | ||
| message: "Add an Oxford comma in '%s'." | ||
| scope: sentence | ||
| level: warning | ||
| nonword: true | ||
| tokens: | ||
| - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| extends: existence | ||
| message: "'%s': Whenever possible, use the active voice instead of the passive voice." | ||
| ignorecase: true | ||
| level: suggestion | ||
| raw: | ||
| - \b(am|are|were|being|is|been|was|be)\b\s* | ||
| tokens: | ||
| - '[\w]+ed' | ||
| - become | ||
| - been | ||
| - begun | ||
| - brought | ||
| - built | ||
| - cast | ||
| - caught | ||
| - chosen | ||
| - come | ||
| - cut | ||
| - dealt | ||
| - done | ||
| - drawn | ||
| - forbidden | ||
| - found | ||
| - given | ||
| - gone | ||
| - gotten | ||
| - held | ||
| - hidden | ||
| - kept | ||
| - known | ||
| - led | ||
| - let | ||
| - made | ||
| - put | ||
| - quit | ||
| - read | ||
| - seen | ||
| - sent | ||
| - sped | ||
| - spent | ||
| - stuck | ||
| - swept | ||
| - taken | ||
| - understood | ||
| - written |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| extends: existence | ||
| message: "Using '%s' is unnecessary. Remove." | ||
| link: https://github.com/opensearch-project/documentation-website/blob/main/TERMS.md | ||
| ignorecase: true | ||
| level: warning | ||
| action: | ||
| name: remove | ||
| tokens: | ||
| - please |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| extends: existence | ||
| message: Use an en dash (--) with no space on either side in a range of numbers. | ||
| link: https://github.com/opensearch-project/documentation-website/blob/main/STYLE_GUIDE.md#numbers-and-measurement | ||
| nonword: true | ||
| level: error | ||
| tokens: | ||
| - '\b\d+ *[-] *\d+\b' |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| extends: repetition | ||
| message: "'%s' is repeated." | ||
| level: error | ||
| alpha: true | ||
| tokens: | ||
| - '[^\s]+' |
Oops, something went wrong.