feat: check writing with Vale

.github/workflows/review-docs.yaml

@@ -0,0 +1,27 @@
+---
+name: Review docs
+
+on:
+  pull_request:
+    paths:
+      - "ospo-book/content/*/*.md"
+
+jobs:
+  review-docs:
+    name: Review docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Download vale
+        env:
+          BASEURL: https://github.com/errata-ai/vale/releases/download
+          VERSION: 2.29.0
+        run: |
+          mkdir -p .vale/bin && cd .vale/bin
+          wget -O vale.tar.gz --quiet "${BASEURL}/v${VERSION}/vale_${VERSION}_Linux_64-bit.tar.gz"
+          tar xzf vale.tar.gz
+          pwd >> "$GITHUB_PATH"
+      - name: Run vale
+        run: |
+          vale --output=".vale.tmpl" --no-exit ospo-book/content

.vale.ini

@@ -0,0 +1,17 @@
+# Vale is an open-source, command-line tool that brings your editorial style guide to life.
+# source: https://vale.sh
+
+# Styles are stored in the .vale folder
+StylesPath = .vale
+
+# Configured styles can be downloaded with the command: vale sync
+Packages = proselint, alex, Hugo
+
+# Alert suggestions, warnings and alerts
+MinAlertLevel = suggestion
+
+# Configure a dictionary specific to TODO
+Vocab = TODO
+
+[*.md]
+BasedOnStyles = Vale, proselint, alex

.vale.tmpl

@@ -0,0 +1,19 @@
+{{- /* Keep track of our various counts */ -}}
+{{- range .Files}}
+{{- $file := .Path -}}
+{{- range .Alerts -}}
+{{- $line := .Line -}}
+{{- $col := (index .Span 0) -}}
+{{- $title := .Check | quote -}}
+{{- /* Skip Readability comments on line 1 */ -}}
+{{- if and (ne $line 1) (ne $col 1) (not (hasPrefix "Readability" $title)) -}}
+{{- if eq .Severity "error" }}
+::error file={{$file}},line={{$line}},col={{$col}},title={{$title}}::{{.Message}}
+{{- else if eq .Severity "warning" }}
+::warning file={{$file}},line={{$line}},col={{$col}},title={{$title}}::{{.Message}}
+{{- else }}
+::notice file={{$file}},line={{$line}},col={{$col}},title={{$title}}::{{.Message}}
+{{- end}}
+{{- end}}
+{{- end}}
+{{- end}}

.vale/.vale-config/2-Hugo.ini

@@ -0,0 +1,8 @@
+[*.md]
+# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}})
+TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
+(\[.+\]\({{< .+ >}}\))
+
+# Exclude `{{<  myshortcode `This is some <b>HTML</b>, ... >}}`
+BlockIgnores = (?sm)^({{[%<] [^{]*? [%>]}})\n$, \
+(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}})

.vale/Vocab/TODO/accept.txt

@@ -0,0 +1,3 @@
+NGO(s)
+OSPO(s)
+VMware

.vale/alex/Ablist.yml

@@ -0,0 +1,248 @@
+---
+extends: substitution
+message: When referring to a person, consider using '%s' instead of '%s'.
+ignorecase: true
+level: warning
+action:
+  name: replace
+swap:
+  ablebodied: non-disabled
+  addict: person with a drug addiction|person recovering from a drug addiction
+  addicts: people with a drug addiction|people recovering from a drug addiction
+  adhd: disorganized|distracted|energetic|hyperactive|impetuous|impulsive|inattentive|restless|unfocused
+  afflicted with MD: person who has muscular dystrophy
+  afflicted with a disability: has a disability|person with a disability|people with
+    disabilities
+  afflicted with a intellectual disability: person with an intellectual disability
+  afflicted with a polio: polio|person who had polio
+  afflicted with aids: person with AIDS
+  afflicted with an injury: sustain an injury|receive an injury
+  afflicted with disabilities: has a disability|person with a disability|people with
+    disabilities
+  afflicted with injuries: sustain injuries|receive injuries
+  afflicted with intellectual disabilities: person with an intellectual disability
+  afflicted with multiple sclerosis: person who has multiple sclerosis
+  afflicted with muscular dystrophy: person who has muscular dystrophy
+  afflicted with polio: polio|person who had polio
+  afflicted with psychosis: person with a psychotic condition|person with psychosis
+  afflicted with schizophrenia: person with schizophrenia
+  aids victim: person with AIDS
+  alcohol abuser: someone with an alcohol problem
+  alcoholic: someone with an alcohol problem
+  amputee: person with an amputation
+  anorexic: thin|slim
+  asylum: psychiatric hospital|mental health hospital
+  barren: empty|sterile|infertile
+  batshit: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of
+    mental illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  bedlam: chaos|hectic|pandemonium
+  binge: enthusiastic|spree
+  bipolar: fluctuating|person with bipolar disorder
+  birth defect: has a disability|person with a disability|people with disabilities
+  blind eye to: careless|heartless|indifferent|insensitive
+  blind to: careless|heartless|indifferent|insensitive
+  blinded by: careless|heartless|indifferent|insensitive
+  bony: thin|slim
+  bound to a wheelchair: uses a wheelchair
+  buckteeth: person with prominent teeth|prominent teeth
+  bucktoothed: person with prominent teeth|prominent teeth
+  challenged: has a disability|person with a disability|people with disabilities
+  cleftlipped: person with a cleft-lip and palate
+  confined to a wheelchair: uses a wheelchair
+  contard: disagreeable|uneducated|ignorant|naive|inconsiderate
+  crazy: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  cretin: creep|fool
+  cripple: person with a limp
+  crippled: person with a limp
+  daft: absurd|foolish
+  deaf and dumb: deaf
+  deaf ear to: careless|heartless|indifferent|insensitive
+  deaf to: careless|heartless|indifferent|insensitive
+  deafened by: careless|heartless|indifferent|insensitive
+  deafmute: deaf
+  delirious: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of
+    mental illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  demented: person with dementia
+  depressed: sad|blue|bummed out|person with seasonal affective disorder|person with
+    psychotic depression|person with postpartum depression
+  detox: treatment
+  detox center: treatment center
+  diffability: has a disability|person with a disability|people with disabilities
+  differently abled: has a disability|person with a disability|people with disabilities
+  disabled: turned off|has a disability|person with a disability|people with disabilities
+  downs syndrome: Down Syndrome
+  dumb: foolish|ludicrous|speechless|silent
+  dummy: test double|placeholder|fake|stub
+  dummyobject: test double|placeholder|fake|stub
+  dummyvalue: test double|placeholder|fake|stub
+  dummyvariable: test double|placeholder|fake|stub
+  dwarf: person with dwarfism|little person|little people|LP|person of short stature
+  dyslexic: person with dyslexia
+  epileptic: person with epilepsy
+  family burden: with family support needs
+  feeble minded: foolish|ludicrous|silly
+  feebleminded: foolish|ludicrous|silly
+  fucktard: disagreeable|uneducated|ignorant|naive|inconsiderate
+  gimp: person with a limp
+  handicapable: has a disability|person with a disability|people with disabilities
+  handicapped: person with a handicap|accessible
+  handicapped parking: accessible parking
+  hare lip: cleft-lip and palate
+  harelip: cleft-lip and palate
+  harelipped: person with a cleft-lip and palate
+  has intellectual issues: person with an intellectual disability
+  hearing impaired: hard of hearing|partially deaf|partial hearing loss|deaf
+  hearing impairment: hard of hearing|partially deaf|partial hearing loss|deaf
+  idiot: foolish|ludicrous|silly
+  imbecile: foolish|ludicrous|silly
+  infantile paralysis: polio|person who had polio
+  insane: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  insanely: incredibly
+  insanity: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of
+    mental illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  insomnia: restlessness|sleeplessness
+  insomniac: person who has insomnia
+  insomniacs: people who have insomnia
+  intellectually disabled: person with an intellectual disability
+  intellectually disabled people: people with intellectual disabilities
+  invalid: turned off|has a disability|person with a disability|people with disabilities
+  junkie: person with a drug addiction|person recovering from a drug addiction
+  junkies: people with a drug addiction|people recovering from a drug addiction
+  lame: boring|dull
+  learning disabled: person with learning disabilities
+  libtard: disagreeable|uneducated|ignorant|naive|inconsiderate
+  loony: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  loony bin: chaos|hectic|pandemonium
+  low iq: foolish|ludicrous|unintelligent
+  lunacy: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  lunatic: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of
+    mental illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  madhouse: chaos|hectic|pandemonium
+  maniac: fanatic|zealot|enthusiast
+  manic: person with schizophrenia
+  mental: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  mental case: rude|malicious|mean|disgusting|incredible|vile|person with symptoms
+    of mental illness|person with mental illness|person with symptoms of a mental
+    disorder|person with a mental disorder
+  mental defective: rude|malicious|mean|disgusting|incredible|vile|person with symptoms
+    of mental illness|person with mental illness|person with symptoms of a mental
+    disorder|person with a mental disorder
+  mentally ill: rude|malicious|mean|disgusting|incredible|vile|person with symptoms
+    of mental illness|person with mental illness|person with symptoms of a mental
+    disorder|person with a mental disorder
+  midget: person with dwarfism|little person|little people|LP|person of short stature
+  mongoloid: person with Down Syndrome
+  moron: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  moronic: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of
+    mental illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  multiple sclerosis victim: person who has multiple sclerosis
+  neurotic: has an anxiety disorder|obsessive|pedantic|niggly|picky
+  nuts: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  o.c.d: has an anxiety disorder|obsessive|pedantic|niggly|picky
+  o.c.d.: has an anxiety disorder|obsessive|pedantic|niggly|picky
+  ocd: has an anxiety disorder|obsessive|pedantic|niggly|picky
+  panic attack: fit of terror|scare
+  paraplegic: person with paraplegia
+  psycho: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental
+    illness|person with mental illness|person with symptoms of a mental disorder|person
+    with a mental disorder
+  psychopathology: rude|malicious|mean|disgusting|incredible|vile|person with symptoms
+    of mental illness|person with mental illness|person with symptoms of a mental
+    disorder|person with a mental disorder
+  psychotic: person with a psychotic condition|person with psychosis
+  quadriplegic: person with quadriplegia
+  rehab: treatment
+  rehab center: treatment center
+  restricted to a wheelchair: uses a wheelchair
+  retard: silly|dullard|person with Down Syndrome|person with developmental disabilities|delay|hold
+    back
+  retarded: silly|dullard|person with Down Syndrome|person with developmental disabilities|delay|hold
+    back
+  retards: "sillies|dullards|people with developmental disabilities|people with Down\u2019\
+    s Syndrome|delays|holds back"
+  sane: correct|adequate|sufficient|consistent|valid|coherent|sensible|reasonable
+  sanity check: check|assertion|validation|smoke test
+  schizo: person with schizophrenia
+  schizophrenic: person with schizophrenia
+  senile: person with dementia
+  short bus: silly|dullard|person with Down Syndrome|person with developmental disabilities|delay|hold
+    back
+  simpleton: foolish|ludicrous|unintelligent
+  small person: person with dwarfism|little person|little people|LP|person of short
+    stature
+  sociopath: person with a personality disorder|person with psychopathic personality
+  sociopaths: people with psychopathic personalities|people with a personality disorder
+  spastic: person with cerebral palsy|twitch|flinch
+  spaz: person with cerebral palsy|twitch|flinch|hectic
+  special: has a disability|person with a disability|people with disabilities
+  special needs: has a disability|person with a disability|people with disabilities
+  special olympians: athletes|Special Olympics athletes
+  special olympic athletes: athletes|Special Olympics athletes
+  specially abled: has a disability|person with a disability|people with disabilities
+  stammering: stuttering|disfluency of speech
+  stroke victim: individual who has had a stroke
+  stupid: foolish|ludicrous|unintelligent
+  stutterer: person who stutters
+  suffer from aids: person with AIDS
+  suffer from an injury: sustain an injury|receive an injury
+  suffer from injuries: sustain injuries|receive injuries
+  suffering from a disability: has a disability|person with a disability|people with
+    disabilities
+  suffering from a polio: polio|person who had polio
+  suffering from a stroke: individual who has had a stroke
+  suffering from aids: person with AIDS
+  suffering from an injury: sustain an injury|receive an injury
+  suffering from an intellectual disability: person with an intellectual disability
+  suffering from disabilities: has a disability|person with a disability|people with
+    disabilities
+  suffering from injuries: sustain injuries|receive injuries
+  suffering from intellectual disabilities: person with an intellectual disability
+  suffering from multiple sclerosis: person who has multiple sclerosis
+  suffering from polio: polio|person who had polio
+  suffering from psychosis: person with a psychotic condition|person with psychosis
+  suffering from schizophrenia: person with schizophrenia
+  suffers from MD: person who has muscular dystrophy
+  suffers from aids: person with AIDS
+  suffers from an injury: sustain an injury|receive an injury
+  suffers from disabilities: has a disability|person with a disability|people with
+    disabilities
+  suffers from injuries: sustain injuries|receive injuries
+  suffers from intellectual disabilities: person with an intellectual disability
+  suffers from multiple sclerosis: person who has multiple sclerosis
+  suffers from muscular dystrophy: person who has muscular dystrophy
+  suffers from polio: polio|person who had polio
+  suffers from psychosis: person with a psychotic condition|person with psychosis
+  suffers from schizophrenia: person with schizophrenia
+  tourettes disorder: Tourette syndrome
+  tourettes syndrome: Tourette syndrome
+  vertically challenged: person with dwarfism|little person|little people|LP|person
+    of short stature
+  victim of a stroke: individual who has had a stroke
+  victim of aids: person with AIDS
+  victim of an injury: sustain an injury|receive an injury
+  victim of injuries: sustain injuries|receive injuries
+  victim of multiple sclerosis: person who has multiple sclerosis
+  victim of polio: polio|person who had polio
+  victim of psychosis: person with a psychotic condition|person with psychosis
+  wacko: foolish|ludicrous|unintelligent
+  whacko: foolish|ludicrous|unintelligent
+  wheelchair bound: uses a wheelchair

.vale/alex/Condescending.yml

@@ -0,0 +1,16 @@
+---
+extends: existence
+message: Using '%s' may come across as condescending.
+link: https://css-tricks.com/words-avoid-educational-writing/
+level: error
+ignorecase: true
+tokens:
+  - obvious
+  - obviously
+  - simple
+  - simply
+  - easy
+  - easily
+  - of course
+  - clearly
+  - everyone knows