vale: group Qt rules under styles/Qt by language, structure, and mechanics
Group all existing Qt styles and the new styles that map to the
corresponding R-rules in the skill-language-style. The R-rules are
classified into deterministic (i.e. rules that are concrete and easy
to check using vale) and non-deterministic (i.e. rules that are vague).
The README file in each subdirectory under the differnt Qt styles,
document which of the rules map to an R-rule.
The rules are reclassified by what they check and consolidated under a
single styles/Qt style, using Vale's nested-style directories so each
subdirectory resolves to its own dotted rule name:
- styles/Qt/Language: wording, grammar, tone, and terminology
(Qt.Language.*).
- styles/Qt/Structure: QDoc topic/document structure, such as briefs,
titles, anchors, tables, and module sections (Qt.Structure.*).
- styles/Qt/Mechanics: line length, spacing, repetition, and spelling
(Qt.Mechanics.*).
The new rules in some of these groups map to a non-deterministic R-rule,
to verify if a vague R-rule can be a determinitic vale rule. Most of
these rules are still disabled in the config, until we decide what
to do with them.
The README.md file in each new subdirectory, representing the groups
list the enabled and disabled rules, known gaps, and (in
styles/Qt/Structure) the Microsoft-overlap audit, and Vale engine
quirks that applied across all three groups. The
top-level README.md is also updated to match the new paths and rule
names.
Fold in fixes found while validating the regrouped rules against
`vale test --coverage`:
- Qt.Language.Headings: `scope` was a single comma-joined string. Vale's
mapstructure decoding wraps a bare string into a one-element list
instead of splitting it on commas, so the rule never matched. Written
as a YAML list instead.
- Qt.Structure.QDocImageAltInlineCmd: `scope: text.comment.image.alt`
never exposes image alt text as lintable content in this Vale build.
Rewritten to `scope: raw`, matched directly against the `\image {...}`
command text. This rule is enabled in .vale-qdoc.ini, so this is a real
production behavior fix, not just a test-coverage one.
- Qt.Structure.ListIntroPresence: the original `doc(p)` sibling-selector
design is infeasible (Vale's `doc()` dialect has no working CSS
sibling-combinator support). Redesigned as a `scope: raw` heuristic
that flags a `\list`/`\table` immediately preceded by a QDoc command
line instead of prose.
- Qt.Language.AltTextPassive and Qt.Language.PassiveVoice removed:
Microsoft.Passive (already enabled, default `scope: text`) already
covers the same be-verb-plus-past-participle content, including alt
text, with a larger irregular-verb list. Neither Qt rule added
detection Microsoft.Passive didn't already provide.
- Qt.Language.LatinTerms now extends Microsoft.Foreign directly
(`swap+`) instead of duplicating a substitution rule for the same
category.
- Qt.Language.WordyConstructions: added `vocab: false`. A bounded-
repetition, multi-word token ("causes ... to occur") silently stopped
matching once the real .vale-qdoc.ini's Vocab list was active, even
though no matched word was itself a vocab entry.
Task-number: QTBUG-151121
Change-Id: I9d7c36a873b9e1416aa3adaf9303938ad1b88841
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
| commit | c7ea62c548e09832f5e13748a5822b45accdc0b1 |
| parent | a2d3ce78a19be0215b9873d4ce909cd9c6006cca |
| author | Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> |
| committer | Venugopal Shivashankar <Venugopal.Shivashankar@qt.io> |
| commit time | Fri, 2 Oct 2026 16:03:10 +0000 |
- M vale_linter_config/.vale-qdoc.ini
- M vale_linter_config/README.md
- A vale_linter_config/styles/Qt/Language/AdmonitionHedging.yml
- A vale_linter_config/styles/Qt/Language/AmbiguousPronoun.yml
- A vale_linter_config/styles/Qt/Language/CausationSinceAs.yml
- R100 vale_linter_config/styles/Qt/FutureTense.yml
- R086 vale_linter_config/styles/Qt/Headings.yml
- A vale_linter_config/styles/Qt/Language/HedgingWords.yml
- A vale_linter_config/styles/Qt/Language/Idioms.yml
- A vale_linter_config/styles/Qt/Language/ImperativeBrief.yml
- A vale_linter_config/styles/Qt/Language/LatinTerms.yml
- R100 vale_linter_config/styles/Qt/LoseLoose.yml
- A vale_linter_config/styles/Qt/Language/Numbers.yml
- A vale_linter_config/styles/Qt/Language/PropertySignalOpener.yml
- R100 vale_linter_config/styles/Qt/QDocPageTitle.yml
- A vale_linter_config/styles/Qt/Language/QtTerminology.yml
- A vale_linter_config/styles/Qt/Language/README.md
- A vale_linter_config/styles/Qt/Language/TermConsistency.yml
- A vale_linter_config/styles/Qt/Language/WordyConstructions.yml
- A vale_linter_config/styles/Qt/Language/WordyFillers.yml
- A vale_linter_config/styles/Qt/Language/WordyQuantifier.yml
- D vale_linter_config/styles/Qt/LatinTerms.yml
- R100 vale_linter_config/styles/Qt/LineLength.yml
- A vale_linter_config/styles/Qt/Mechanics/README.md
- R100 vale_linter_config/styles/Qt/Repetition.yml
- R100 vale_linter_config/styles/Qt/Spacing.yml
- R100 vale_linter_config/styles/Qt/Spelling.yml
- R100 vale_linter_config/styles/Qt/Underfilled.yml
- D vale_linter_config/styles/Qt/QDocImageAlt.yml
- D vale_linter_config/styles/Qt/QDocImageAltInlineCmd.yml
- A vale_linter_config/styles/Qt/Structure/AltTextClassNames.yml
- A vale_linter_config/styles/Qt/Structure/AltTextFormat.yml
- A vale_linter_config/styles/Qt/Structure/ExampleGroupIngroup.yml
- A vale_linter_config/styles/Qt/Structure/ExampleTitleRepetition.yml
- A vale_linter_config/styles/Qt/Structure/KeyboardShortcutFormat.yml
- A vale_linter_config/styles/Qt/Structure/ListIntroPresence.yml
- A vale_linter_config/styles/Qt/Structure/ListItemPunctuation.yml
- A vale_linter_config/styles/Qt/Structure/MenuPathFormat.yml
- A vale_linter_config/styles/Qt/Structure/ModuleExamplesSection.yml
- A vale_linter_config/styles/Qt/Structure/ModuleReferenceSection.yml
- A vale_linter_config/styles/Qt/Structure/NoSpaceBeforeBrace.yml
- R100 vale_linter_config/styles/Qt/QDocAnchorAPIName.yml
- R100 vale_linter_config/styles/Qt/QDocBrief.yml
- R100 vale_linter_config/styles/Qt/QDocDeprecatedVersionOrder.yml
- A vale_linter_config/styles/Qt/Structure/QDocImageAlt.yml
- A vale_linter_config/styles/Qt/Structure/QDocImageAltInlineCmd.yml
- R100 vale_linter_config/styles/Qt/QDocVersionClauseOrder.yml
- A vale_linter_config/styles/Qt/Structure/QMLGenericTypes.yml
- A vale_linter_config/styles/Qt/Structure/README.md
- A vale_linter_config/styles/Qt/Structure/SaTargetVocab.yml
- A vale_linter_config/styles/Qt/Structure/SectionLinkAntiPattern.yml
- A vale_linter_config/styles/Qt/Structure/TableEmptyCell.yml
- A vale_linter_config/styles/Qt/Structure/TableGenericHeaders.yml
- A vale_linter_config/styles/Qt/Structure/UIElementMarkup.yml
- M vale_linter_config/tests/LineLength.qdoc
- M vale_linter_config/tests/QDocHeadings.qdoc
- M vale_linter_config/tests/QDocImageAlt.qdoc
- M vale_linter_config/tests/SharedContent.qdocinc