~whereswaldon/arborchat

0a41a60c21bc80c8c5a6e57e5465dd82b58174ee — Amolith a month ago 93a7b47 master
integrate vale

This massive patch attemps to standardise out documentation. For those
unfamiliar with it, Vale is "a syntax-aware linter for prose built with
speed and extensibility in mind" [1]. I built on Vale's
implementation [2] of Google's style guide [3] with specifics for Arbor
and the vocabulary we've started using.

[1]: https://github.com/errata-ai/vale
[2]: https://github.com/errata-ai/Google
[3]: https://developers.google.com/style/

I didn't modify any of the docs that are already written so some of them
will have a ton of errors. Once Arbor's style has been reviewed and a
bit more polished, I'll go through and start implementing the
recommended changes. To that end, install Vale [1], run it on a few
files, and see what the output says. Feedback is welcome.

[1]: https://errata-ai.gitbook.io/vale/getting-started/installation
A .vale.ini => .vale.ini +5 -0
@@ 0,0 1,5 @@
StylesPath = styles/
MinAlertLevel = suggestion
[*.{md,txt}]
BasedOnStyles = Arbor, Vale
BlockIgnores = (\((http.*://|\.\/|\/).*?\))

A styles/Arbor/AMPM.yml => styles/Arbor/AMPM.yml +9 -0
@@ 0,0 1,9 @@
extends: existence
message: "Use 'AM' or 'PM' (preceded by a space)."
link: 'https://developers.google.com/style/word-list'
level: error
nonword: true
tokens:
  - '\d{1,2}[AP]M'
  - '\d{1,2} ?[ap]m'
  - '\d{1,2} ?[aApP]\.[mM]\.'

A styles/Arbor/Acronyms.yml => styles/Arbor/Acronyms.yml +65 -0
@@ 0,0 1,65 @@
extends: conditional
message: "Spell out '%s', if it's unfamiliar to the audience."
link: 'https://developers.google.com/style/abbreviations'
level: suggestion
ignorecase: false
# Ensures that the existence of 'first' implies the existence of 'second'.
first: '\b([A-Z]{3,5})\b'
second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
# ... with the exception of these:
exceptions:
  - API
  - ASP
  - CLI
  - CPU
  - CSS
  - CSV
  - DEBUG
  - DOM
  - DPI
  - FAQ
  - GCC
  - GDB
  - GET
  - GPU
  - GTK
  - GUI
  - HTML
  - HTTP
  - HTTPS
  - IDE
  - JAR
  - JSON
  - JSX
  - LESS
  - LLDB
  - NET
  - NOTE
  - NVDA
  - OSS
  - PATH
  - PDF
  - PHP
  - POST
  - RAM
  - REPL
  - RSA
  - SCM
  - SCSS
  - SDK
  - SQL
  - SSH
  - SSL
  - SVG
  - TBD
  - TCP
  - TODO
  - URI
  - URL
  - US
  - USB
  - UTF
  - XML
  - XSS
  - YAML
  - ZIP

A styles/Arbor/Colons.yml => styles/Arbor/Colons.yml +9 -0
@@ 0,0 1,9 @@
extends: existence
message: "'%s' should be in lowercase."
link: 'https://developers.google.com/style/colons'
nonword: true
level: warning
tokens:
  - ':\s[A-Z]'
exceptions:
  - : Arbor

A styles/Arbor/Contractions.yml => styles/Arbor/Contractions.yml +31 -0
@@ 0,0 1,31 @@
extends: substitution
message: "Feel free to use '%s' instead of '%s'."
link: 'https://developers.google.com/style/contractions'
level: suggestion
ignorecase: true
scope: sentence
action:
  name: replace
swap:
  are not: aren't
  cannot: can't
  could not: couldn't
  did not: didn't
  do not: don't
  does not: doesn't
  has not: hasn't
  have not: haven't
  how is: how's
  is not: isn't
  it is: it's
  should not: shouldn't
  that is: that's
  they are: they're
  was not: wasn't
  we are: we're
  we have: we've
  were not: weren't
  what is: what's
  when is: when's
  where is: where's
  will not: won't

A styles/Arbor/DateFormat.yml => styles/Arbor/DateFormat.yml +9 -0
@@ 0,0 1,9 @@
extends: existence
message: "Use 'July 31, 2016' format, not '%s'."
link: 'https://developers.google.com/style/dates-times'
ignorecase: true
level: error
nonword: true
tokens:
  - '\d{1,2}(?:\.|/)\d{1,2}(?:\.|/)\d{4}'
  - '\d{1,2} (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) \d{4}'

A styles/Arbor/Ellipses.yml => styles/Arbor/Ellipses.yml +9 -0
@@ 0,0 1,9 @@
extends: existence
message: "In general, don't use an ellipsis."
link: 'https://developers.google.com/style/ellipses'
nonword: true
level: warning
action:
  name: remove
tokens:
  - '\.\.\.'

A styles/Arbor/EmDash.yml => styles/Arbor/EmDash.yml +12 -0
@@ 0,0 1,12 @@
extends: existence
message: "Don't put a space before or after a dash."
link: 'https://developers.google.com/style/dashes'
nonword: true
level: error
action:
  name: edit
  params:
    - remove
    - ' '
tokens:
  - '\s[—–]\s'

A styles/Arbor/EnDash.yml => styles/Arbor/EnDash.yml +13 -0
@@ 0,0 1,13 @@
extends: existence
message: "Use an em dash ('—') instead of '–'."
link: 'https://developers.google.com/style/dashes'
nonword: true
level: error
action:
  name: edit
  params:
    - replace
    - '-'
    - '—'
tokens:
  - '–'

A styles/Arbor/Exclamation.yml => styles/Arbor/Exclamation.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Try to avoid exclamation points except when conveying friendliness."
link: 'https://developers.google.com/style/exclamation-points'
nonword: true
level: warning
tokens:
  - '\w!(?:\s|$)'

A styles/Arbor/FirstPerson.yml => styles/Arbor/FirstPerson.yml +13 -0
@@ 0,0 1,13 @@
extends: existence
message: "Avoid first-person pronouns such as '%s'."
link: 'https://developers.google.com/style/pronouns#personal-pronouns'
ignorecase: true
level: warning
nonword: true
tokens:
  - (?:^|\s)I\s
  - (?:^|\s)I,\s
  - \bI'm\b
  - \bme\b
  - \bmy\b
  - \bmine\b

A styles/Arbor/Gender.yml => styles/Arbor/Gender.yml +9 -0
@@ 0,0 1,9 @@
extends: existence
message: "Don't use '%s' as a gender-neutral pronoun."
link: 'https://developers.google.com/style/pronouns#gender-neutral-pronouns'
level: error
ignorecase: true
tokens:
  - he/she
  - s/he
  - \(s\)he

A styles/Arbor/GenderBias.yml => styles/Arbor/GenderBias.yml +45 -0
@@ 0,0 1,45 @@
extends: substitution
message: "Consider using '%s' instead of '%s'."
link: 'https://developers.google.com/style/inclusive-documentation'
ignorecase: true
level: error
swap:
  (?:alumna|alumnus):          graduate
  (?:alumnae|alumni):          graduates
  air(?:m[ae]n|wom[ae]n):      pilot(s)
  anchor(?:m[ae]n|wom[ae]n):   anchor(s)
  authoress:                   author
  camera(?:m[ae]n|wom[ae]n):   camera operator(s)
  chair(?:m[ae]n|wom[ae]n):    chair(s)
  congress(?:m[ae]n|wom[ae]n): member(s) of congress
  door(?:m[ae]|wom[ae]n):      concierge(s)
  draft(?:m[ae]n|wom[ae]n):    drafter(s)
  fire(?:m[ae]n|wom[ae]n):     firefighter(s)
  fisher(?:m[ae]n|wom[ae]n):   fisher(s)
  fresh(?:m[ae]n|wom[ae]n):    first-year student(s)
  garbage(?:m[ae]n|wom[ae]n):  waste collector(s)
  lady lawyer:                 lawyer
  ladylike:                    courteous
  landlord:                    building manager
  mail(?:m[ae]n|wom[ae]n):     mail carriers
  man and wife:                husband and wife
  man enough:                  strong enough
  mankind:                     human kind
  manmade:                     manufactured
  manpower:                    personnel
  men and girls:               men and women
  middle(?:m[ae]n|wom[ae]n):   intermediary
  news(?:m[ae]n|wom[ae]n):     journalist(s)
  ombuds(?:man|woman):         ombuds
  oneupmanship:                upstaging
  poetess:                     poet
  police(?:m[ae]n|wom[ae]n):   police officer(s)
  repair(?:m[ae]n|wom[ae]n):   technician(s)
  sales(?:m[ae]n|wom[ae]n):    salesperson or sales people
  service(?:m[ae]n|wom[ae]n):  soldier(s)
  steward(?:ess)?:             flight attendant
  tribes(?:m[ae]n|wom[ae]n):   tribe member(s)
  waitress:                    waiter
  woman doctor:                doctor
  woman scientist[s]?:         scientist(s)
  work(?:m[ae]n|wom[ae]n):     worker(s)

A styles/Arbor/HeadingPunctuation.yml => styles/Arbor/HeadingPunctuation.yml +13 -0
@@ 0,0 1,13 @@
extends: existence
message: "Don't put a period at the end of a heading."
link: 'https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings'
nonword: true
level: warning
scope: heading
action:
  name: edit
  params:
    - remove
    - '.'
tokens:
  - '[a-z0-9][.](?:\s|$)'

A styles/Arbor/Headings.yml => styles/Arbor/Headings.yml +30 -0
@@ 0,0 1,30 @@
extends: capitalization
message: "'%s' should use sentence-style capitalization."
link: 'https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings'
level: warning
scope: heading
match: $sentence
exceptions:
  - Arbor
  - Azure
  - CLI
  - Code
  - Cosmos
  - Docker
  - Emmet
  - I
  - Kubernetes
  - Linux
  - macOS
  - Marketplace
  - MongoDB
  - REPL
  - Studio
  - Sprig
  - Sprout
  - TypeScript
  - URLs
  - Visual
  - VS
  - Windows
  - Wisteria

A styles/Arbor/Incomplete.yml => styles/Arbor/Incomplete.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Avoid using '%s'."
link: 'https://developers.google.com/style/tense'
ignorecase: true
level: warning
tokens:
  - fixme

A styles/Arbor/Latin.yml => styles/Arbor/Latin.yml +11 -0
@@ 0,0 1,11 @@
extends: substitution
message: "Use '%s' instead of '%s'."
link: 'https://developers.google.com/style/abbreviations'
ignorecase: true
level: error
nonword: true
action:
  name: replace
swap:
  '\b(?:eg|e\.g\.)[\s,]': for example
  '\b(?:ie|i\.e\.)[\s,]': that is

A styles/Arbor/LyHyphens.yml => styles/Arbor/LyHyphens.yml +14 -0
@@ 0,0 1,14 @@
extends: existence
message: "'%s' doesn't need a hyphen."
link: 'https://developers.google.com/style/hyphens'
level: error
ignorecase: false
nonword: true
action:
  name: edit
  params:
    - replace
    - '-'
    - ' '
tokens:
  - '\s[^\s-]+ly-'

A styles/Arbor/OptionalPlurals.yml => styles/Arbor/OptionalPlurals.yml +12 -0
@@ 0,0 1,12 @@
extends: existence
message: "Don't use plurals in parentheses such as in '%s'."
link: 'https://developers.google.com/style/plurals-parentheses'
level: error
nonword: true
action:
  name: edit
  params:
    - remove
    - '(s)'
tokens:
  - '\b\w+\(s\)'

A styles/Arbor/Ordinal.yml => styles/Arbor/Ordinal.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Spell out all ordinal numbers ('%s') in text."
link: 'https://developers.google.com/style/numbers'
level: error
nonword: true
tokens:
  - \d+(?:st|nd|rd|th)

A styles/Arbor/OxfordComma.yml => styles/Arbor/OxfordComma.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Use the Oxford comma in '%s'."
link: 'https://developers.google.com/style/commas'
scope: sentence
level: warning
tokens:
  - '(?:[^,]+,){1,}\s\w+\s(?:and|or)'

A styles/Arbor/Parens.yml => styles/Arbor/Parens.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Use parentheses judiciously."
link: 'https://developers.google.com/style/parentheses'
nonword: true
level: suggestion
tokens:
  - '\(.+\)'

A styles/Arbor/Passive.yml => styles/Arbor/Passive.yml +184 -0
@@ 0,0 1,184 @@
extends: existence
link: 'https://developers.google.com/style/voice'
message: "In general, use active voice instead of passive voice ('%s')."
ignorecase: true
level: suggestion
raw:
  - \b(am|are|were|being|is|been|was|be)\b\s*
tokens:
  - '[\w]+ed'
  - awoken
  - beat
  - become
  - been
  - begun
  - bent
  - beset
  - bet
  - bid
  - bidden
  - bitten
  - bled
  - blown
  - born
  - bought
  - bound
  - bred
  - broadcast
  - broken
  - brought
  - built
  - burnt
  - burst
  - cast
  - caught
  - chosen
  - clung
  - come
  - cost
  - crept
  - cut
  - dealt
  - dived
  - done
  - drawn
  - dreamt
  - driven
  - drunk
  - dug
  - eaten
  - fallen
  - fed
  - felt
  - fit
  - fled
  - flown
  - flung
  - forbidden
  - foregone
  - forgiven
  - forgotten
  - forsaken
  - fought
  - found
  - frozen
  - given
  - gone
  - gotten
  - ground
  - grown
  - heard
  - held
  - hidden
  - hit
  - hung
  - hurt
  - kept
  - knelt
  - knit
  - known
  - laid
  - lain
  - leapt
  - learnt
  - led
  - left
  - lent
  - let
  - lighted
  - lost
  - made
  - meant
  - met
  - misspelt
  - mistaken
  - mown
  - overcome
  - overdone
  - overtaken
  - overthrown
  - paid
  - pled
  - proven
  - put
  - quit
  - read
  - rid
  - ridden
  - risen
  - run
  - rung
  - said
  - sat
  - sawn
  - seen
  - sent
  - set
  - sewn
  - shaken
  - shaven
  - shed
  - shod
  - shone
  - shorn
  - shot
  - shown
  - shrunk
  - shut
  - slain
  - slept
  - slid
  - slit
  - slung
  - smitten
  - sold
  - sought
  - sown
  - sped
  - spent
  - spilt
  - spit
  - split
  - spoken
  - spread
  - sprung
  - spun
  - stolen
  - stood
  - stridden
  - striven
  - struck
  - strung
  - stuck
  - stung
  - stunk
  - sung
  - sunk
  - swept
  - swollen
  - sworn
  - swum
  - swung
  - taken
  - taught
  - thought
  - thrived
  - thrown
  - thrust
  - told
  - torn
  - trodden
  - understood
  - upheld
  - upset
  - wed
  - wept
  - withheld
  - withstood
  - woken
  - won
  - worn
  - wound
  - woven
  - written
  - wrung

A styles/Arbor/Periods.yml => styles/Arbor/Periods.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Don't use periods with acronyms or initialisms such as '%s'."
link: 'https://developers.google.com/style/abbreviations'
level: error
nonword: true
tokens:
  - '\b(?:[A-Z]\.){3,}'

A styles/Arbor/Quotes.yml => styles/Arbor/Quotes.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Commas and periods go inside quotation marks."
link: 'https://developers.google.com/style/quotation-marks'
level: error
nonword: true
tokens:
  - '"[^"]+"[.,?]'

A styles/Arbor/Ranges.yml => styles/Arbor/Ranges.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Don't add words such as 'from' or 'between' to describe a range of numbers."
link: 'https://developers.google.com/style/hyphens'
nonword: true
level: warning
tokens:
  - '(?:from|between)\s\d+\s?-\s?\d+'

A styles/Arbor/Semicolons.yml => styles/Arbor/Semicolons.yml +8 -0
@@ 0,0 1,8 @@
extends: existence
message: "Use semicolons judiciously."
link: 'https://developers.google.com/style/semicolons'
nonword: true
scope: sentence
level: suggestion
tokens:
  - ';'

A styles/Arbor/Slang.yml => styles/Arbor/Slang.yml +11 -0
@@ 0,0 1,11 @@
extends: existence
message: "Don't use internet slang abbreviations such as '%s'."
link: 'https://developers.google.com/style/abbreviations'
ignorecase: true
level: error
tokens:
  - 'tl;dr'
  - ymmv
  - rtfm
  - imo
  - fwiw

A styles/Arbor/Spacing.yml => styles/Arbor/Spacing.yml +8 -0
@@ 0,0 1,8 @@
extends: existence
message: "'%s' should have one space."
link: 'https://developers.google.com/style/sentence-spacing'
level: error
nonword: true
tokens:
  - '[.?!] {2,}[A-Z]'
  - '[.?!][A-Z]'

A styles/Arbor/Spelling.yml => styles/Arbor/Spelling.yml +8 -0
@@ 0,0 1,8 @@
extends: existence
message: "In general, use American spelling instead of '%s'."
link: 'https://developers.google.com/style/spelling'
ignorecase: true
level: warning
tokens:
  - '(?:\w+)nised?'
  - '(?:\w+)logue'

A styles/Arbor/Units.yml => styles/Arbor/Units.yml +8 -0
@@ 0,0 1,8 @@
extends: existence
message: "Put a nonbreaking space between the number and the unit in '%s'."
link: 'https://developers.google.com/style/units-of-measure'
nonword: true
level: error
tokens:
  - \d+(?:B|kB|MB|GB|TB)
  - \d+(?:ns|ms|s|min|h|d)

A styles/Arbor/Will.yml => styles/Arbor/Will.yml +7 -0
@@ 0,0 1,7 @@
extends: existence
message: "Avoid using '%s'."
link: 'https://developers.google.com/style/tense'
ignorecase: true
level: warning
tokens:
  - will

A styles/Arbor/WordList.yml => styles/Arbor/WordList.yml +87 -0
@@ 0,0 1,87 @@
extends: substitution
message: "Use '%s' instead of '%s'."
link: 'https://developers.google.com/style/word-list'
level: warning
ignorecase: false
action:
  name: replace
swap:
  '(?:API Console|dev|developer) key': API key
  '(?:cell ?phone|smart ?phone)': phone|mobile phone
  '(?:Community node|community Node|community node)': Community Node
  '(?:dev|developer|APIs) console': API console
  '(?:e-mail|Email|E-mail)': email
  '(?:file ?path|path ?name)': path
  '(?:Identity node|identity Node|identity node)': Identity Node
  '(?:kill|terminate|abort)': stop|exit|cancel|end
  '(?:OAuth ?2|Oauth)': OAuth 2.0
  '(?:ok|Okay)': OK|okay
  '(?:Reply node|reply Node|reply node)': Reply Node
  '(?:WiFi|wifi)': Wi-Fi
  '[\.]+apk': APK
  '3\-D': 3D
  'Google (?:I\-O|IO)': Google I/O
  'tap (?:&|and) hold': touch & hold
  'un(?:check|select)': clear
  above: preceding
  account name: username
  action bar: app bar
  admin: administrator
  Ajax: AJAX
  Android device: Android-powered device
  android: Android
  API explorer: APIs Explorer
  app: application
  approx\.: approximately
  arbor: Arbor
  authN: authentication
  authZ: authorization
  autoupdate: automatically update
  cellular data: mobile data
  cellular network: mobile network
  chapter: documents|pages|sections
  check box: checkbox
  check: select
  CLI: command-line tool
  click on: click|click in
  Cloud: Google Cloud Platform|GCP
  Container Engine: Kubernetes Engine
  content type: media type
  curated roles: predefined roles
  data are: data is
  Developers Console: Google API Console|API Console
  disabled?: turn off|off
  ephemeral IP address: ephemeral external IP address
  fewer data: less data
  file name: filename
  firewalls: firewall rules
  functionality: capability|feature
  Google account: Google Account
  Google accounts: Google Accounts
  Googling: search with Google
  grayed-out: unavailable
  HTTPs: HTTPS
  http: HTTP
  in order to: to
  ingest: import|load
  k8s: Kubernetes
  long press: touch & hold
  network IP address: internal IP address
  omnibox: address bar
  open-source: open source
  overview screen: recents screen
  regex: regular expression
  SHA1: SHA-1|HAS-SHA1
  sign into: sign in to
  sign-?on: single sign-on
  sprout: Sprout
  static IP address: static external IP address
  stylesheet: style sheet
  synch: sync
  syncthing: Syncthing
  tablename: table name
  tablet: device
  touch: tap
  url:  URL
  vs\.: versus
  World Wide Web: web

A styles/Arbor/meta.json => styles/Arbor/meta.json +4 -0
@@ 0,0 1,4 @@
{
  "feed": "https://github.com/errata-ai/Google/releases.atom",
  "vale_version": ">=1.0.0"
}

A styles/vocab.txt => styles/vocab.txt +15 -0
@@ 0,0 1,15 @@
whereswaldon
Syncthing
untrusted
http
spacebar
sinensis
Katerina
Inkscape
sourcehut
repo
Waldon
endian
subtree
plaintext
ASCII